Getting Started Guide
For use with Red Hat JBoss Data Grid 7.0
Abstract
Part I. Introducing Red Hat JBoss Data Grid
Chapter 1. Red Hat JBoss Data Grid
- Schemaless key-value store – JBoss Data Grid is a NoSQL database that provides the flexibility to store different objects without a fixed data model.
- Grid-based data storage – JBoss Data Grid is designed to easily replicate data across multiple nodes.
- Elastic scaling – Adding and removing nodes is simple and non-disruptive.
- Multiple access protocols – It is easy to access the data grid using REST, Memcached, Hot Rod, or simple map-like API.
1.1. Supported Configurations
1.2. Components and Versions
1.3. Red Hat JBoss Data Grid Usage Modes
- Remote Client-Server mode
- Library mode
1.3.1. Remote Client-Server Mode
- easier scaling of the data grid.
- easier upgrades of the data grid without impact on client applications.
$JBOSS_HOME/bin/standalone.sh
$JBOSS_HOME\bin\standalone.bat
$JBOSS_HOME/bin/domain.sh
$JBOSS_HOME\bin\domain.bat
1.3.2. Library Mode
- transactions
- listeners and notifications
1.4. Red Hat JBoss Data Grid Benefits
Benefits of JBoss Data Grid
- Performance
- Accessing objects from local memory is faster than accessing objects from remote data stores (such as a database). JBoss Data Grid provides an efficient way to store in-memory objects coming from a slower data source, resulting in faster performance than a remote data store. JBoss Data Grid also offers optimization for both clustered and non clustered caches to further improve performance.
- Consistency
- Storing data in a cache carries the inherent risk: at the time it is accessed, the data may be outdated (stale). To address this risk, JBoss Data Grid uses mechanisms such as cache invalidation and expiration to remove stale data entries from the cache. Additionally, JBoss Data Grid supports JTA, distributed (XA) and two-phase commit transactions along with transaction recovery and a version API to remove or replace data according to saved versions.
- Massive Heap and High Availability
- In JBoss Data Grid, applications no longer need to delegate the majority of their data lookup processes to a large single server database for performance benefits. JBoss Data Grid employs techniques such as replication and distribution to completely remove the bottleneck that exists in the majority of current enterprise applications.
Example 1.1. Massive Heap and High Availability Example
In a sample grid with 16 blade servers, each node has 2 GB storage space dedicated for a replicated cache. In this case, all the data in the grid is copies of the 2 GB data. In contrast, using a distributed grid (assuming the requirement of one copy per data item, resulting in the capacity of the overall heap being divided by two) the resulting memory backed virtual heap contains 16 GB data. This data can now be effectively accessed from anywhere in the grid. In case of a server failure, the grid promptly creates new copies of the lost data and places them on operational servers in the grid. - Scalability
- A significant benefit of a distributed data grid over a replicated clustered cache is that a data grid is scalable in terms of both capacity and performance. Adding a node to JBoss Data Grid increases throughput and capacity for the entire grid. JBoss Data Grid uses a consistent hashing algorithm that limits the impact of adding or removing a node to a subset of the nodes instead of every node in the grid.Due to the even distribution of data in JBoss Data Grid, the only upper limit for the size of the grid is the group communication on the network. The network's group communication is minimal and restricted only to the discovery of new nodes. Nodes are permitted by all data access patterns to communicate directly via peer-to-peer connections, facilitating further improved scalability. JBoss Data Grid clusters can be scaled up or down in real time without requiring an infrastructure restart. The result of the real time application of changes in scaling policies results in an exceptionally flexible environment.
- Data Distribution
- JBoss Data Grid uses consistent hash algorithms to determine the locations for keys in clusters. Benefits associated with consistent hashing include:Data distribution ensures that sufficient copies exist within the cluster to provide durability and fault tolerance, while not an abundance of copies, which would reduce the environment's scalability.
- cost effectiveness.
- speed.
- deterministic location of keys with no requirements for further metadata or network traffic.
- Persistence
- JBoss Data Grid exposes a
CacheStore
interface and several high-performance implementations, including the JDBC Cache stores and file system based cache stores. Cache stores can be used to populate the cache when it starts and to ensure that the relevant data remains safe from corruption. The cache store also overflows data to the disk when required to prevent running out of memory. - Language bindings
- JBoss Data Grid supports both the popular Memcached protocol, with existing clients for a large number of popular programming languages, as well as an optimized JBoss Data Grid specific protocol called Hot Rod. As a result, instead of being restricted to Java, JBoss Data Grid can be used for any major website or application. Additionally, remote caches can be accessed using the HTTP protocol via a RESTful API.
- Management
- In a grid environment of several hundred or more servers, management is an important feature. JBoss Operations Network, the enterprise network management software, is the best tool to manage multiple JBoss Data Grid instances. JBoss Operations Network's features allow easy and effective monitoring of the Cache Manager and cache instances.
- Remote Data Grids
- Rather than scale up the entire application server architecture to scale up your data grid, JBoss Data Grid provides a Remote Client-Server mode which allows the data grid infrastructure to be upgraded independently from the application server architecture. Additionally, the data grid server can be assigned different resources than the application server and also allow independent data grid upgrades and application redeployment within the data grid.
1.5. Red Hat JBoss Data Grid Version Information
JBoss Data Grid Product | Infinispan Version |
---|---|
JBoss Data Grid 6.0.0 | Infinispan 5.1.5 |
JBoss Data Grid 6.0.1 | Infinispan 5.1.7 |
JBoss Data Grid 6.1.0 | Infinispan 5.2.4 |
JBoss Data Grid 6.2.0 | Infinispan 6.0.1 |
JBoss Data Grid 6.3.0 | Infinispan 6.1.0 |
JBoss Data Grid 6.3.1 | Infinispan 6.1.1 |
JBoss Data Grid 6.4.0 | Infinispan 6.2.0 |
JBoss Data Grid 6.4.1 | Infinispan 6.2.1 |
JBoss Data Grid 6.5.0 | Infinispan 6.3.0 |
JBoss Data Grid 6.5.1 | Infinispan 6.3.1 |
JBoss Data Grid 6.6.0 | Infinispan 6.4.0 |
JBoss Data Grid 7.0.0 | Infinispan 8.3.0 |
Note
1.6. Red Hat JBoss Data Grid Cache Architecture

Figure 1.1. Red Hat JBoss Data Grid Cache Architecture
- Elements that a user cannot directly interact with are depicted within a dark grey box in the diagram. In Remote Client-Server mode, this includes Persistent Store, Cache, Cache Manager, L1 Cache, and Server Module. In Library mode, user cannot directly interact with Persistent Store and L1 Cache.
- Elements that a user can interact directly with are depicted in a light grey box in the diagram. In Remote Client-Server mode, this includes the Application and the Cache Client. In Library mode, users are allowed to interact with the Cache and Cache Manager, as well as the Application.
JBoss Data Grid's cache architecture includes the following elements:
- The Persistent Store is an optional component. It can permanently store the cached entries for restoration after a data grid shutdown.
- The Level 1 Cache (or L1 Cache) stores remote cache entries after they are initially accessed, preventing unnecessary remote fetch operations for each subsequent use of the same entries.
- The Cache Manager controls the life cycle of Cache instances and can store and retrieve them when required.
- The Cache is the main component for storage and retrieval of the key-value entries.
In Library mode, the Application (user code) can interact with the Cache and Cache Manager components directly. In this case the Application resides in the same Java Virtual Machine (JVM) and can call Cache and Cache Manager Java API methods directly.
1.7. Red Hat JBoss Data Grid APIs
- Cache
- Batching
- Grouping
- Persistence (formerly CacheStore)
- ConfigurationBuilder
- Externalizable
- Notification (also known as the Listener API because it deals with Notifications and Listeners)
- The Asynchronous API (can only be used in conjunction with the Hot Rod Client in Remote Client-Server Mode)
- The REST Interface
- The Memcached Interface
- The Hot Rod Interface
- The RemoteCache API
Part II. Download and Install Red Hat JBoss Data Grid
Chapter 2. Download Red Hat JBoss Data Grid
2.1. Red Hat JBoss Data Grid Installation Prerequisites
2.2. Java Virtual Machine
2.3. Install OpenJDK on Red Hat Enterprise Linux
Procedure 2.1. Install OpenJDK on Red Hat Enterprise Linux
Subscribe to the Base Channel
Obtain the OpenJDK from the RHN base channel. Your installation of Red Hat Enterprise Linux is subscribed to this channel by default.Install the Package
Use the yum utility to install OpenJDK:$ sudo yum install java-1.8.0-openjdk-devel
Verify that OpenJDK is the System Default
Ensure that the correct JDK is set as the system default as follows:- Log in as a user with root privileges and run the alternatives command:
$ /usr/sbin/alternatives --config java
- Select
/usr/lib/jvm/java-1.8.0-openjdk-${java-version}.x86_64/bin/java
. - Use the following command to set
javac
:$ /usr/sbin/alternatives --config javac
- Select
/usr/lib/jvm/java-1.8.0-openjdk-${java-version}.x86_64/bin/javac
.
2.4. Download and Install JBoss Data Grid
- Download JBoss Data Grid from the Red Hat Customer Portal.
- Verify the downloaded files.
- Install JBoss Data Grid.
2.4.1. Download Red Hat JBoss Data Grid
Procedure 2.2. Download JBoss Data Grid
- Log into the Customer Portal at https://access.redhat.com.
- Click thebutton near the top of the page.
- In the Product Downloads page, click .
- Select the appropriate JBoss Data Grid version from the Version: drop down menu.
- Download the appropriate files from the list that is displayed.
2.4.2. About the Red Hat Customer Portal
- Manage and maintain Red Hat entitlements and support contracts.
- Download officially-supported software.
- Access product documentation and the Red Hat Knowledgebase.
- Contact Global Support Services.
- File bugs against Red Hat products.
2.4.3. Checksum Validation
2.4.4. Verify the Downloaded File
Procedure 2.3. Verify the Downloaded File
- To verify that a file downloaded from the Red Hat Customer Portal is error-free, access the portal site and go to that package's Software Details page. The Software Details page displays the
MD5
andSHA256
"checksum" values. Use the checksum values to check the integrity of the file. - Open a terminal window and run either the
md5sum
orsha256sum
command, with the downloaded file as an argument. The program displays the checksum value for the file as the output for the command. - Compare the checksum value returned by the command to the corresponding value displayed on the Software Details page for the file.
Note
Microsoft Windows does not come equipped with a checksum tool. Windows operating system users have to download a third-party product instead.
If the two checksum values are identical then the file has not been altered or corrupted and is, therefore, safe to use.
2.4.5. Install Red Hat JBoss Data Grid
Locate the appropriate version, platform, and file type and download Red Hat JBoss Data Grid from the Customer Portal.
Procedure 2.4. Install JBoss Data Grid
- Copy the downloaded JBoss Data Grid package to the preferred location on your machine.
- Run the following command to extract the downloaded JBoss Data Grid package:
$ unzip JDG_PACKAGE
Replace JDG_PACKAGE with the name of the JBoss Data Grid usage mode package downloaded from the Red Hat Customer Portal. - The resulting unzipped directory will now be referred to as $JDG_HOME.
2.4.6. Red Hat Documentation Site
Chapter 3. Install and Use the Maven Repositories
3.1. About Maven
Important
3.2. Required Maven Repositories
- The JBoss Data Grid Maven Repository
- The
techpreview-all-repository
(https://maven.repository.redhat.com/techpreview/all/)
3.3. Install the Maven Repository
- On your local file system (Section 3.3.1, “Local File System Repository Installation”).
- On Apache Web Server (Section 3.3.2, “Apache httpd Repository Installation”).
- With a Maven repository manager (Section 3.3.3, “Maven Repository Manager Installation”).
3.3.1. Local File System Repository Installation
Procedure 3.1. Local File System Repository Installation (JBoss Data Grid)
Log Into the Customer Portal
In a browser window, navigate to the Customer Portal page (https://access.redhat.com/home) and log in.Download the JBoss Data Grid Repository File
Download thejboss-datagrid-{VERSION}-maven-repository.zip
file from the Red Hat Customer Portal.- Unzip the file to a directory on your local file system (for example
$JDG_HOME/projects/maven-repositories/
).
jboss-datagrid-${jdg-version}-maven-repository
directory, which contains the Maven repository in a subdirectory entitled maven-repository/
.
3.3.2. Apache httpd Repository Installation
Note
- Open a web browser and access https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=data.grid
- Find
Red Hat JBoss Data Grid 7.0.0 Maven Repository
in the list. - Click thebutton to download a .zip file containing the repository.
- Unzip the files in a directory that is web accessible on the Apache server.
- Configure Apache to allow read access and directory browsing in the created directory.
3.3.3. Maven Repository Manager Installation
- Apache Archiva: http://archiva.apache.org/
- JFrog Artifactory: http://www.jfrog.com/products.php
- Sonatype Nexus: http://nexus.sonatype.org/ For details, see Section B.1, “Install the JBoss Enterprise Application Platform Repository Using Nexus”.
3.4. Configure the Maven Repository
settings.xml
file. This file may be configured in one of two locations:
- User level - Maven user settings are located in the
${user.home}/.m2/
directory:- For Linux or Mac environments this is typically
~/.m2/
- For Windows environments this is typically
\Documents and Settings\.m2\
or\Users\.m2\
- Global level - Settings for all users on a machine, assuming they are all using the same Maven installation, is typically provided in
${maven.home}/conf/settings.xml
3.4.1. Configuring the JBoss Data Grid Maven Repository in an Offline Environment
- The JBoss Data Grid Maven repository has been downloaded to the internal network where it will be referenced.
- An internal repository, such as Sonatype Nexus or Apache Archiva, is available on the network that contains Maven dependencies.
Procedure 3.2. Configure the JBoss Data Grid Maven Repository for Offline Usage
- Install the downloaded JBoss Data Grid Maven repository locally, following the instructions in Section 3.3.1, “Local File System Repository Installation”.
- Update the
settings.xml
to point to the locally extracted repository, as seen in Section 3.4, “Configure the Maven Repository”. A sample configuration is shown below:<?xml version="1.0" encoding="UTF-8"?> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>jboss-datagrid-repository</id> <repositories> <repository> <id>jboss-datagrid-repository</id> <name>JBoss Data Grid Maven Repository</name> <url>file:///path/to/jboss-datagrid-7.0.0.GA-maven-repository/maven-repository</url> <layout>default</layout> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>false</enabled> <updatePolicy>never</updatePolicy> </snapshots> </repository> <pluginRepositories> <pluginRepository> <id>jboss-datagrid-repository</id> <name>JBoss Data Grid Maven Repository</name> <url>file:///path/to/jboss-datagrid-7.0.0.GA-maven-repository/maven-repository</url> <layout>default</layout> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>false</enabled> <updatePolicy>never</updatePolicy> </snapshots> </pluginRepository> </pluginRepositories> </profile> </profiles> <activeProfiles> <!-- make the profile active by default --> <activeProfile>jboss-datagrid-repository</activeProfile> </activeProfiles> </settings>
- Ensure that projects may now be built locally.
3.4.2. Next Steps
Part III. Supported Containers for JBoss Data Grid
Chapter 4. Using JBoss Data Grid with Supported Containers
- Java SE, started by your application.
- As a standalone JBoss Data Grid server.
- Bundled as a library in your application, deployed to an application server, and started by your application. For example, JBoss Data Grid can be used with Tomcat or Weblogic.
- Inside an OSGi runtime environment, in this case, Apache Karaf.
4.1. Deploy JBoss Data Grid in JBoss EAP (Library Mode)
Note
- Add a dependency to the
jboss-deployment-structure.xml
file. - Add a dependency to the
MANIFEST.MF
file. - Generate the
MANIFEST.MF
file via Maven.
Add the following configuration to the jboss-deployment-structure.xml
file:
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2"> <deployment> <dependencies> <module name="org.infinispan" slot="jdg-7.0" services="export"/> </dependencies> </deployment> </jboss-deployment-structure>
Note
jboss-deployment-structure.xml
file, see the Red Hat JBoss Enterprise Application Platform documentation.
Add a dependency to the MANIFEST.MF
files as follows:
Example 4.1. Example MANIFEST.MF File
Manifest-Version: 1.0 Dependencies: org.infinispan:jdg-7.0 services
- JBoss Data Grid Core:
Dependencies: org.infinispan:jdg-7.0 services
- Embedded Query:
Dependencies: org.infinispan:jdg-7.0 services, org.infinispan.query:jdg-7.0 services, org.infinispan.query.dsl:jdg-7.0 services
- JDBC Cache Store:
Dependencies: org.infinispan:jdg-7.0 services, org.infinispan.persistence.jdbc:jdg-7.0 services
- JPA Cache Store:
Dependencies: org.infinispan:jdg-7.0 services, org.infinispan.persistence.jpa:jdg-7.0 services
- LevelDB Cache Store:
Dependencies: org.infinispan:jdg-7.0 services, org.infinispan.persistence.leveldb:jdg-7.0 services
- CDI:
Dependencies: org.infinispan:jdg-7.0 services, org.infinispan.cdi:jdg-7.0 meta-inf
The MANIFEST.MF
file is generated during the build (specifically during the JAR or WAR process). As an alternative to adding a dependency to the MANIFEST.MF
file, configure the dependency directly in Maven by adding the following to the pom.xml
file:
<plugin> <artifactId>maven-war-plugin</artifactId> <version>2.4</version> <configuration> <failOnMissingWebXml>false</failOnMissingWebXml> <archive> <manifestEntries> <Dependencies>org.infinispan:jdg-7.0 services</Dependencies> </manifestEntries> </archive> </configuration> </plugin>
4.2. Deploy JBoss Data Grid in JBoss EAP (Remote Client-Server Mode)
Note
- Add a dependency to the
jboss-deployment-structure.xml
file. - Add a dependency to the
MANIFEST.MF
file.
Add the following configuration to the jboss-deployment-structure.xml
file:
<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2"> <deployment> <dependencies> <module name="org.infinispan.commons" slot="jdg-7.0" services="export"/> <module name="org.infinispan.client.hotrod" slot="jdg-7.0" services="export"/> </dependencies> </deployment> </jboss-deployment-structure>
Note
jboss-deployment-structure.xml
file, see the Red Hat JBoss Enterprise Application Platform documentation.
Add a dependency to the MANIFEST.MF
files as follows:
Example 4.2. Example MANIFEST.MF File
Manifest-Version: 1.0 Dependencies: org.infinispan.commons:jdg-7.0 services, org.infinispan.client.hotrod:jdg-7.0 services
- Basic Hot Rod client:
org.infinispan.commons:jdg-7.0 services, org.infinispan.client.hotrod:jdg-7.0 services
- Hot Rod client with Remote Query functionality:
org.infinispan.commons:jdg-7.0 services, org.infinispan.client.hotrod:jdg-7.0 services, org.infinispan.query.dsl:jdg-7.0 services, org.jboss.remoting3
4.2.1. Using Custom Classes with the Hot Rod client
- Option 1: Reference the deployment's class loader in the configuration builder for the Hot Rod client, as seen in the below example:
Example 4.3. Referencing the custom class loader in the ConfigurationBuilder instance
import org.infinispan.client.hotrod.configuration.ConfigurationBuilder; [...] ConfigurationBuilder config = new ConfigurationBuilder(); config.marshaller(new GenericJBossMarshaller(Thread.currentThread().getContextClassLoader()));
- Option 2: Install the custom classes as their own module within JBoss EAP, and add a dependency on the newly created module should be added to the JBoss Data Grid module at
${EAP_HOME}/modules/system/layers/base/org/infinispan/commons/jdg-6.x/module.xml
.
4.3. Deploy JBoss Data Grid in JBoss Enterprise Web Server
4.4. Deploy Web Applications on WebLogic Server (Library Mode)
The prerequisites to deploy the web applications are as follows:
- WebLogic Server 12c.
- JBoss Data Grid Library (Embedded) mode.
Procedure 4.1. Deploying Web Applications on a WebLogic Server
Create Web Applications
Create a web application and add the libraries in theWEB-INF
folder.Create a weblogic.xml Deployment Descriptor
Create aweblogic.xml
deployment descriptor with the following elements in it:<?xml version="1.0" encoding="UTF-8"?> <weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.bea.com/ns/weblogic/90 http://www.bea.com/ns/weblogic/90/weblogic-web-app.xsd"> <container-descriptor> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> </weblogic-web-app>
Note
Theprefer-web-inf-classes
class indicates that the libraries and the classes in theWEB-INF/lib
folder is preferred over the default libraries bundled in the WebLogic server. For example, thecommons-pool.jar
file in the WebLogic server has version 1.4 and is automatically loaded by the classloader, but the Hot Rod client uses a newer version of this library.Pack the Web Application into a Web Archive File
Create a web application archive (WAR) file of the web application and verify that the JBoss Data Grid libraries are in theWEB-INF
folder along with the WebLogic deployment descriptor file.Deploy the Application onto WebLogic Server
To deploy the web application using the Infinispan CDI module, stop the WebLogic server if it is running, apply the patch on it (Patch filep17424706_121200_Generic.zip
) and restart the WebLogic server. If the Infinispan CDI module is not being used, deploy the web application normally.For more information about applying patch to the WebLogic Server, see the Oracle patch database on the Oracle website.
4.5. Deploy Web Applications on WebLogic Server (Remote Client-Server Mode)
Procedure 4.2. Deploying Web Applications on a WebLogic Server
- To install the WebLogic server, see http://docs.oracle.com/cd/E24329_01/doc.1211/e24492/toc.htm.
- Configure JBoss Data Grid in Remote Client-Server mode, define cache, cache container, and endpoint configuration. After configuration, start JBoss Data Grid to confirm that the Hot Rod endpoint is listening on the configured port. For information about configuring JBoss Data Grid in Remote Client-Server, see Chapter 7, Run Red Hat JBoss Data Grid in Remote Client-Server Mode.
- Create a web application and add the
infinispan-remote
library as a dependency if Maven is used. - Create a
weblogic.xml
deployment descriptor with the following elements in it:<?xml version="1.0" encoding="UTF-8"?> <weblogic-web-app xmlns="http://www.bea.com/ns/weblogic/90" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.bea.com/ns/weblogic/90 http://www.bea.com/ns/weblogic/90/weblogic-web-app.xsd"> <container-descriptor> <prefer-web-inf-classes>true</prefer-web-inf-classes> </container-descriptor> </weblogic-web-app>
Note
Theprefer-web-inf-classes
class indicates that the libraries and classes in theWEB-INF/lib
folder are preferred over the default libraries bundled in the WebLogic server. For example, thecommons-pool.jar
file in the WebLogic server has version 1.4 and is automatically loaded by the classloader, however the Hot Rod client uses a newer version of this library. - Add deployment descriptor file in the
WEB-INF
folder. - Ensure that the
infinispan-remote
dependency is added to thepom.xml
file, then use a Maven plugin to create a web archive.Alternatively, create the web archive manually and add the library manually. - Deploy the application in the WebLogic server and verify that the Hot Rod client embedded inside the web application connects to the remote JBoss Data Grid server.
4.6. Running Red Hat JBoss Data Grid in Karaf (OSGi)
4.6.1. Running a Deployment of JBoss Data Grid in Karaf (Remote Client-Server)
features
file, located in org/infinispan/infinispan-remote/${VERSION}
. This file lists all dependencies for the Hot Rod client in OSGi, while also making it simpler to install the feature into Karaf (version 2.3.3 or 3.0).
4.6.2. Installing the Hot Rod client feature in Karaf
Configure the Red Hat JBoss Data Grid Maven Repository.
Procedure 4.3. Install the Hot Rod Feature in Karaf
Karaf 2.3.3
For Karaf 2.3.3 use the following commands:karaf@root> features:addUrl mvn:org.infinispan/infinispan-remote/${VERSION}/xml/features
karaf@root> features:install infinispan-remote
- Verify that the feature was successfully installed as follows:
karaf@root> features:list //output
Karaf 3.0.0
For Karaf use the following commands.karaf@root> feature:repo-add mvn:org.infinispan/infinispan-remote/${VERSION}/xml/features
karaf@root> feature:install infinispan-remote
- Verify that the feature was successfully installed:
karaf@root> feature:list
Alternatively, use the-i
command parameter to install the Hot Rod Client feature using the following:karaf@root()> feature:repo-add -i mvn:org.infinispan/infinispan-remote/${VERSION}/xml/features
4.6.3. Installing Red Hat JBoss Data Grid in Karaf (Library Mode)
features
file, which defines all required dependencies.
features
file:
- Register the feature repositories inside Karaf.
- Install the features contained in the repositories.
Procedure 4.4. Installing bundles using the features
file
Start the Karaf console
Start the Karaf console using the following commands:$ cd $APACHE_KARAF_HOME/bin $ ./karaf
Register a feature repository
Register a feature repository as follows:- For Karaf 2.3.3:
karaf@root()> features:addUrl mvn:org.infinispan/infinispan-embedded/${VERSION}/xml/features
karaf@root> features:install infinispan-embedded
- For Karaf 3.0.0:
karaf@root()> feature:repo-add mvn:org.infinispan/infinispan-embedded/${VERSION}/xml/features
karaf@root> feature:install infinispan-embedded
JBoss Data Grid runs in library mode using Karaf.
mvn:<groupId>/<artifactId>/<version>/xml/features
Important
Important
Chapter 5. Running Red Hat JBoss Data Grid with Apache Camel
5.1. The camel-jbossdatagrid Component
camel-jbossdatagrid
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-jbossdatagrid
producer usesGET
,PUT
,REMOVE
, andCLEAR
operations. The local producer is also supported with a replicated or distributed cache. - Remote Camel Producer
In Remote Client-Server mode, the Camel producer can send messages using Hot Rod.
- Remote Camel Consumer
In Client-Server mode, receives cache change notifications and sends them to be processed. The events are processed asynchronously.
camel-jbossdatagrid
dependency must be added to the pom.xml
file to run JBoss Data Grid with Camel:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jbossdatagrid</artifactId> <version>7.0.0.ER4-redhat-1</version> <!-- use the same version as your JBoss Data Grid version --> </dependency>
Note
camel-jbossdatagrid
component ships with JBoss Data Grid, and is not included in the JBoss Fuse 6.1 or JBoss Fuse Service Works 6.0 distributions.
FileComponent
is referred to in a URI as file
, which creates FileEndpoints
.
The following URI format is used for camel-jbossdatagrid
:
infinispan://hostname?[options]
The producer can create and send messages to a local or remote JBoss Data Grid cache configured in the registry. If a cacheContainer
is present, the cache will be either local or remote, depending on whether the cacheContainer
instance is a DefaultCacheManager
or RemoteCacheManager
. If it is not present, the cache will try to connect to remote cache using the supplied hostname/port.
Name | Default Value | Type | Context | Description |
---|---|---|---|---|
cacheContainer | null | CacheContainer | Shared | Reference to a org.infinispan.manager.CacheContainer in the Registry. |
cacheName | null | String | Shared | The cache name to use. If not specified, the default cache is used. |
command | PUT | String | Producer | The operation to perform. Only the PUT, GET, REMOVE, and CLEAR values are currently supported. |
eventTypes | null | Set<String> | Consumer |
A comma separated list of the event types to register. By default, this listens for all event types. Possible values are defined in
org.infinispan.notifications.cachelistener.event.Event.Type .
Example:
...?eventTypes=CACHE_ENTRY_EXPIRED,CACHE_ENTRY_EVICTED,... |
sync | true | Boolean | Consumer | By default the consumer will receive notifications synchronously by the same thread that process the cache operation. Remote HotRod listeners support only asynchronous notification. |
clustered | false | Boolean | Consumer | By default the consumer will only receive local events. By using this option, the consumer also listens to events originated on other nodes in the cluster. The only events available for clustered listeners are CACHE_ENTRY_CREATED , CACHE_ENTRY_REMOVED , and CACHE_ENTRY_MODIFIED . |
A list of all available operations, along with their header information, is found below:
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationPut | Embedded / Remote | Puts a key/value pair in the cache, optionally with expiration | CamelInfinispanKey , CamelInfinispanValue | CamelInfinispanLifespanTime , CamelInfinispanLifespanTimeUnit , CamelInfinispanMaxIdleTime , CamelInfinispanMaxIdleTimeUnit , CamelInfinispanIgnoreReturnValues | CamelInfinispanOperationResult |
CamelInfinispanOperationPutAsync | Asynchronously puts a key/value pair in the cache, optionally with expiration | ||||
CamelInfinispanOperationPutIfAbsent | Puts a key/value pair in the cache if it did not exist, optionally with expiration | ||||
CamelInfinispanOperationPutIfAbsentAsync | Asynchronously puts a key/value pair in the cache if it did not exist, optionally with expiration |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationPutAll | Embedded / Remote | Adds multiple entries to a cache, optionally with expiration | CamelInfinispanMap | CamelInfinispanLifespanTime , CamelInfinispanLifespanTimeUnit , CamelInfinispanMaxIdleTime , CamelInfinispanMaxIdleTimeUnit | |
CamelInfinispanOperationPutAllAsync | Asynchronously adds multiple entries to a cache, optionally with expiration |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationGet | Embedded / Remote | Retrieves the value associated with a specific key from the cache | CamelInfinispanKey |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationContainsKey | Embedded / Remote | Determines whether a cache contains a specific key | CamelInfinispanKey | CamelInfinispanOperationResult |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationContainsValue | Embedded / Remote | Determines whether a cache contains a specific value | CamelInfinispanKey |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationRemove | Embedded / Remote | Removes an entry from a cache, optionally only if the value matches a given one | CamelInfinispanKey | CamelInfinispanValue | CamelInfinispanOperationResult |
CamelInfinispanOperationRemoveAsync | Asynchronously removes an entry from a cache, optionally only if the value matches a given one |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationReplace | Embedded / Remote | Conditionally replaces an entry in the cache, optionally with expiration | CamelInfinispanKey , CamelInfinispanValue , CamelInfinispanOldValue | CamelInfinispanLifespanTime , CamelInfinispanLifespanTimeUnit , CamelInfinispanMaxIdleTime , CamelInfinispanMaxIdleTimeUnit , CamelInfinispanIgnoreReturnValues | CamelInfinispanOperationResult |
CamelInfinispanOperationReplaceAsync | Asynchronously conditionally replaces an entry in the cache, optionally with expiration |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationClear | Embedded / Remote | Clears the cache |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationSize | Embedded / Remote | Returns the number of entries in the cache | CamelInfinispanOperationResult |
Operation Name | Context | Description | Required Headers | Optional Headers | Result Header |
---|---|---|---|---|---|
CamelInfinispanOperationQuery | Remote | Executes a query on the cache | CamelInfinispanQueryBuilder | CamelInfinispanOperationResult |
Note
CamelInfinispanIgnoreReturnValues
will receive a null result.
Name | Default Value | Type | Context | Description |
---|---|---|---|---|
CamelInfinispanCacheName | null | String | Shared | The cache participating in the operation or event. |
CamelInfinispanMap | null | Map | Producer | A Map to use in case of the CamelInfinispanOperationPutAll operation. |
CamelInfinispanKey | null | Object | Shared | The key to perform the operation to or the key generating the event. |
CamelInfinispanValue | null | Object | Producer | The value to use for the operation. |
CamelInfinispanOperationResult | null | Object | Producer | The result of the operation. |
CamelInfinispanEventType | null | String | Consumer |
For local cache listeners (non-clustered), one of the following values:
CACHE_ENTRY_ACTIVATED , CACHE_ENTRY_PASSIVATED , CACHE_ENTRY_VISITED , CACHE_ENTRY_LOADED , CACHE_ENTRY_EVICTED , CACHE_ENTRY_CREATED , CACHE_ENTRY_REMOVED , CACHE_ENTRY_MODIFIED
For remote HotRod listeners, one of the following values:
CLIENT_CACHE_ENTRY_CREATED , CLIENT_CACHE_ENTRY_MODIFIED , CLIENT_CACHE_ENTRY_REMOVED , CLIENT_CACHE_FAILOVER .
|
CamelInfinispanIsPre | null | Boolean | Consumer | Infinispan fires two events for each operation when local non-clustered listener is used: one before and one after the operation. For clustered listeners and remote HotRod listeners, Infinispan fires only one event after the operation. |
CamelInfinispanQueryBuilder | null | InfinispanQueryBuilder | Producer | An instance of InfinispanQueryBuilder that, in its build() , defines the query to be executed on the cache. |
CamelInfinispanLifespanTime | null | long | Producer | The Lifespan time of a value inside the cache. Negative values are interpreted as infinity. |
CamelInfinispanTimeUnit | null | String | Producer | The Time Unit of an entry Lifespan Time. |
CamelInfinispanMaxIdleTime | null | long | Producer | The maximum amount of time an entry is allowed to be idle for before it is considered as expired. |
CamelInfinispanMaxIdleTimeUnit | null | String | Producer | The Time Unit of an entry Max Idle Time. |
5.2. Routing with Camel in JBoss Data Grid
from("direct:start") .setHeader(InfinispanConstants.OPERATION, constant(InfinispanConstants.GET)) .setHeader(InfinispanConstants.KEY, constant("123")) .to("infinispan://localhost?cacheContainer=#cacheContainer");
local-camel-producer
, a camel route that uses the camel-jbossdatagrid
component to send data to an embedded cache created by the local-cache
module.
<camelContext id="local-producer" xmlns="http://camel.apache.org/schema/blueprint"> <route> <from uri="timer://local?fixedRate=true&period=5000"/> <setHeader headerName="CamelInfinispanKey"> <constant>CamelTimerCounter</constant> </setHeader> <setHeader headerName="CamelInfinispanValue"> <constant>CamelTimerCounter</constant> </setHeader> <to uri="infinispan://foo?cacheContainer=#cacheManager"/> <to uri="log:local-put?showAll=true"/> </route> </camelContext>
cacheManager
to be instantiated.
cacheManager
bean for Spring XML can be instantiated as follows:
<bean id="cacheManager" class="org.infinispan.manager.DefaultCacheManager" init-method="start" destroy-method="stop"> <constructor-arg type="java.lang.String" value="infinispan.xml"/> </bean>
cacheManager
bean using Blueprint XML.
<bean id="cacheManager" class="org.infinispan.manager.DefaultCacheManager" init-method="start" destroy-method="stop"> <argument value="infinispan.xml" /> </bean>
Note
infinispan.xml
for configuration of the cache. This file must be present on the classpath.
5.3. Remote Query
RemoteCacheManager
, and an example configuration utilizing a RemoteCacheManager
is found below for both Java and blueprint.xml:
from("direct:start") .setHeader(InfinispanConstants.OPERATION, InfinispanConstants.QUERY) .setHeader(InfinispanConstants.QUERY_BUILDER, new InfinispanQueryBuilder() { public Query build(QueryFactory<Query> queryFactory) { return queryFactory.from(User.class).having("name").like("%abc%") .toBuilder().build(); } }) .to("infinispan://localhost?cacheContainer=#cacheManager&cacheName=remote_query_cache") ;
Java RemoteCacheManagerFactory
class:
public class RemoteCacheManagerFactory { ConfigurationBuilder clientBuilder; public RemoteCacheManagerFactory(String hostname, int port) { clientBuilder = new ConfigurationBuilder(); clientBuilder.addServer() .host(hostname).port(port); } public RemoteCacheManager newRemoteCacheManager() { return new RemoteCacheManager(clientBuilder.build()); } }Java
InfinispanQueryExample
class:
public class InfinispanQueryExample { public InfinispanQueryBuilder getBuilder() { return new InfinispanQueryBuilder() { public Query build(QueryFactory<Query> queryFactory) { return queryFactory.from(User.class) .having("name") .like("%abc%") .toBuilder().build(); } } } }blueprint.xml:
<bean id=”remoteCacheManagerFactory” class=“com.jboss.datagrid.RemoteCacheManagerFactory”> <argument value=”localhost”/> <argument value="11222”/> </bean> <bean id=”cacheManager” factory-ref=”remoteCacheManagerFactory” factory-method=“newRemoteCacheManager”> </bean> <bean id="queryBuilder" class="org.example.com.InfinispanQueryExample"/> <camelContext id="route" xmlns="http://camel.apache.org/schema/blueprint"> <route> <from uri="direct:start"/> <setHeader headerName="CamelInfinispanOperation"> <constant>CamelInfinispanOperationQuery</constant> </setHeader> <setHeader headerName="CamelInfinispanQueryBuilder"> <method ref="queryBuilder" method="getBuilder"/> </setHeader> <to uri="infinispan://localhost?cacheContainer=#cacheManager&cacheName=remote_query_cache"/> </route> </camelContext>
remote_query_cache
is an arbitrary name for a cache that holds the data, and the results of the query will be a list of domain objects stored as a CamelInfinispanOperationResult
header.
- The
RemoteCacheManager
must be configured to useProtoStreamMarshaller
. - The
ProtoStreamMarshaller
must be registered with theRemoteCacheManager
's serialization context. - The .proto descriptors for domain objects must be registered with the remote JBoss Data Grid server.
RemoteCacheManager
, see the Remote Querying
section of the Red Hat JBoss Data Grid Infinispan Query Guide.
5.4. Custom Listeners for Embedded Cache
customListener
parameter as shown below:
from("infinispan://?cacheContainer=#myCustomContainer&cacheName=customCacheName&customListener=#myCustomListener") .to("mock:result");
<bean id="myCustomContainer" org.infinispan.manager.DefaultCacheManager" init-method="start" destroy-method="stop"> <argument value="infinispan.xml" /> </bean> <bean id="myCustomListener" class="org.example.com.CustomListener"/> <camelContext id="route" xmlns="http://camel.apache.org/schema/blueprint"> <route> <from uri="infinispan://?cacheContainer=#myCustomContainer&cacheName=customCacheName&customListener=#myCustomListener"/> <to uri="mock:result"/> </route> </camelContext>
myCustomListener
must exist. Users are encouraged to extend the org.apache.camel.component.infinispan.embedded.InfinispanEmbeddedCustomListener
and annotate the resulting class with the @Listener
annotation from org.infinispan.notifications.
Note
5.5. Custom Listeners for Remote Cache
sync=false
must be present. For instance:
from(infinispan://?cacheContainer=#cacheManager&sync=false&customListener=#myCustomListener") .to(mock:result);
Java class:
public class RemoteCacheManagerFactory { ConfigurationBuilder clientBuilder; public RemoteCacheManagerFactory(String hostname, int port) { clientBuilder = new ConfigurationBuilder(); clientBuilder.addServer() .host(hostname).port(port); } public RemoteCacheManager newRemoteCacheManager() { return new RemoteCacheManager(clientBuilder.build()); } }blueprint.xml:
<bean id=”remoteCacheManagerFactory” class=“com.jboss.datagrid.RemoteCacheManagerFactory”> <argument value=”localhost”/> <argument value="11222”/> </bean> <bean id=”cacheManager” factory-ref=”remoteCacheManagerFactory” factory-method=“newRemoteCacheManager”> </bean> <bean id="myCustomListener" class="org.example.com.CustomListener"/> <camelContext id="route" xmlns="http://camel.apache.org/schema/blueprint"> <route> <from uri="infinispan://?cacheContainer=#cacheManager&sync=false&customListener=#myCustomListener"/> <to uri="mock:result"/> </route> </camelContext>
myCustomListener
must exist. Users are encouraged to extend the org.apache.camel.component.infinispan.remote.InfinispanRemoteCustomListener
class and annotate the resulting class with @ClientListener
; this annotation is found in org.infinispan.client.hotrod.annotation.
@ClientListener(includeCurrentState=true, filterFactoryName = "static-filter-factory", converterFactoryName = "static-converter-factory") private static class MyCustomListener extends InfinispanRemoteCustomListener { }
@NamedFactory
must be implemented. A skeleton that implements the necessary methods is shown below:
import org.infinispan.notifications.cachelistener.filter; @NamedFactory(name = "static-converter-factory") public static class StaticConverterFactory implements CacheEventConverterFactory { @Override public CacheEventConverter<Integer, String, CustomEvent> getConverter(Object[] params) { ... } static class StaticConverter implements CacheEventConverter<Integer, String, CustomEvent>, Serializable { @Override public CustomEvent convert(Integer key, String previousValue, Metadata previousMetadata, String value, Metadata metadata, EventType eventType) { ... } } } @NamedFactory(name = "static-filter-factory") public static class StaticCacheEventFilterFactory implements CacheEventFilterFactory { @Override public CacheEventFilter<Integer, String> getFilter(final Object[] params) { ... } static class StaticCacheEventFilter implements CacheEventFilter<Integer, String>, Serializable { @Override public boolean accept(Integer key, String previousValue, Metadata previousMetadata, String value, Metadata metadata, EventType eventType) { ... } } }
Remote Event Listeners
section of the Red Hat JBoss Data Grid Developer Guide.
Note
RemoteCacheManager
and instantiated.
5.6. Red Hat JBoss Data Grid and Red Hat JBoss Fuse
5.6.1. Installing camel-jbossdatagrid for Red Hat JBoss Fuse
camel-jbossdatagrid
, ensure that both JBoss Data Grid 7.0 and JBoss Fuse 6.1 (Full Installation) are installed.
Procedure 5.1. Installing JBoss Data Grid
- For information about installing JBoss Data Grid, see Part II, “Download and Install Red Hat JBoss Data Grid”. Only the following JBoss Data Grid components are required to run the camel component in JBoss Fuse:
- JBoss Data Grid Maven repository.
- The JBoss Data Grid Server package (to use the Hot Rod client).
camel-jbossdatagrid
library is also available in a separate distribution called jboss-datagrid-7.0.0-camel-library
.
Procedure 5.2. Installing JBoss Fuse
Before attempting to install and use Red Hat JBoss Fuse, ensure your system meets the minimum requirements. For supported Platforms and recommended Java Runtime platforms, see the Red Hat JBoss Fuse Installation Guide.
- 700 MB of free disk space
- 2 GB of RAM
Download the JBoss Fuse Full Installation
You can download the Red Hat JBoss Fuse archive from theRed Hat Customer Portal>Downloads>Red Hat JBoss Middleware>Downloads
page, after you register and login to your customer account.When logged in:- Select, listed under in the sidebar menu.
- Select Software Downloads page.from the Version drop-down list on the
- Click thebutton next to the Red Hat JBoss Fuse 6.1.0 distribution file to download.
JBoss Fuse allows you to choose between installations that contain different feature sets. To run JBoss Data Grid with JBoss Fuse, the Full installation is required. The Full installation includes the following:- Apache Karaf
- Apache Camel
- Apache ActiveAMQ
- Apache CXF
- Fuse Management
- Console (hawtio)
- JBI components
Unpacking the Archive
Red Hat JBoss Fuse is installed by unpacking an archive on a system. JBoss Fuse is packaged as a zip file. Using a suitable archive tool, unpack Red Hat JBoss Fuse into a directory to which you have full access.Warning
Do not unpack the archive file into a folder that has spaces in its path name. For example, do not unpack intoC:\Documents and Settings\Greco Roman\Desktop\fusesrc.
Additionally, do not unpack the archive file into a folder that has any of the following special characters in its path name: #, %, ^, ".Adding a Remote Console User
The server's remote command console is not configured with a default user. Before remotely connecting to the server's console, add a user to the configuration.Important
The information in this file is unencrypted so it is not suitable for environments that require strict security.To add a user:- Open
InstallDir/etc/users.properties
in your favorite text editor. - Locate the line
#admin=admin,admin
. This line specifies a useradmin
with the passwordadmin
and the roleadmin
. - Remove the leading # to uncomment the line.
- Replace the first
admin
with a name for the user. - Replace the second
admin
with the password for the user. - Leave the last
admin
as it is, and save the changes.
Note
To access the Fuse Management Console to monitor and manage your Camel routes, ActiveMQ brokers, Web applications, and so on, open a browser to, after starting Red Hat JBoss Fuse.http://localhost:8181/hawtio
Red Hat JBoss Fuse Maven Repositories
To use Maven to build projects, specify the location of the artifacts in a Mavensettings.xml
file.The following JBoss Fuse Maven repository contains the required dependencies for Camel and must be added to thesettings.xml
file.https://repo.fusesource.com/nexus/content/groups/public/
The JBoss Fuse repository runs alongside the JBoss Data Grid repository.JBoss Data Grid includes afeatures.xml
file for Karaf that deploys all artifacts required for thecamel-jbossdatagrid
component. This file is not included in the JBoss Fuse container distribution. Thefeatures.xml
file is injboss-datagrid-7.0.0-maven-repository/org/apache/camel/camel-jbossdatagrid/${version}/
. No further configuration of the JBoss Data Grid repository is required.For more information about installing and getting started with JBoss Fuse, see the Red Hat JBoss Fuse documentation on the Red Hat Customer Portal.
5.7. Red Hat JBoss Data Grid and Red Hat JBoss EAP
5.7.1. Installing camel-jbossdatagrid for Red Hat JBoss Enterprise Application Platform
- Red Hat JBoss EAP
- Red Hat JBoss Fuse
- Red Hat JBoss Data Grid
Note
jdg.version
- the latest version of Red Hat JBoss Data Gridfuse.version
- the latest version of Red Hat JBoss Fuseinfinispan.version
- the version of Infinispan that is included in the latest version of Red Hat JBoss Data Gridcamel.version
- the version of Apache Camel that is included in the latest version of Red Hat JBoss Fuse
camel-jbossdatagrid
, please refer to https://access.redhat.com/articles/115883.
Procedure 5.3. Installing JBoss Data Grid
- For information about installing JBoss Data Grid, see Part II, “Download and Install Red Hat JBoss Data Grid”. Only the following JBoss Data Grid components are required to run the camel component in JBoss EAP:
- JBoss Data Grid Maven repository.
- The JBoss Data Grid Server package (to use the Hot Rod client).
camel-jbossdatagrid
library is also available in a separate distribution called jboss-datagrid-${jdg.version}-camel-library
.
Procedure 5.4. Installing JBoss EAP
- Before attempting to install and use Red Hat JBoss EAP ensure your system meets the minimum requirements as documented in Red Hat JBoss EAP Installation Guide.
Unpacking the Archive
Red Hat JBoss EAP is installed by unpacking an archive on a system, as JBoss EAP is packaged as a zip file; using a suitable archive tool, unpack Red Hat JBoss EAP into a directory to which you have full access.Warning
Do not unpack the archive file into a folder that has spaces in its path name. For example, do not unpack intoC:\Documents and Settings\Greco Roman\Desktop\JBoss.
Additionally, do not unpack the archive file into a folder that has any of the following special characters in its path name: #, %, ^, ".- Once the archive has been extracted JBoss EAP will have been successfully installed. For more information on installation options refer to the Red Hat JBoss EAP Installation Guide.
- If JBoss Data Grid is being used in Library mode then refer to Section 4.1, “Deploy JBoss Data Grid in JBoss EAP (Library Mode)” to ensure the necessary dependencies have been installed.
- If JBoss Data Grid is being used in Remote Client-Server mode then refer to Section 4.2, “Deploy JBoss Data Grid in JBoss EAP (Remote Client-Server Mode)” to ensure the necessary dependencies have been installed.
5.7.2. Deploy Camel with EAP:
5.7.2.1. Add development and runtime dependencies
pom.xml
(if using Maven).
Procedure 5.5. Add Camel from Fuse
- Ensure that the Fuse repository has been added to the
pom.xml
:<repository> <id>fusesource</id> <name>FuseSource Release Repository</name> <url>https://repo.fusesource.com/nexus/content/groups/public/</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </repository>
- Add the Camel components as a dependency in the
pom.xml
:<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-core</artifactId> <version>${camel.version}</version> </dependency>
Procedure 5.6. Add camel-jbossdatagrid to the deployment
- Follow the instructions in Chapter 3, Install and Use the Maven Repositories to add the maven repository.
- Add camel-jbossdatagrid as a dependency in the
pom.xml
:<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jbossdatagrid</artifactId> <version>${jdg.version}</version> </dependency>
- Add in the remaining JBoss Data Grid dependencies depending on which functionality is in use:
<!-- If Remote Camel Producer is used add the following dependency --> <dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-remote</artifactId> <version>${infinispan.version}</version> </dependency> <!-- If the Local Camel Producer or Local Camel Consumer are in use add --> <!-- the following dependency --> <dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-embedded</artifactId> <version>${infinispan.version}</version> </dependency>
5.7.2.2. Optionally: Add runtime dependencies as a JBoss EAP Module
Note
pom.xml
will need to have the scope
set to "provided" for any dependencies provided as modules. For example:
<dependency> <groupId>org.apache.camel</groupId> <artifactId>camel-jbossdatagrid</artifactId> <scope>provided</scope> <version>${jdg.version}</version> </dependency>
jboss-datagrid-${jdg.version}-camel-library.zip
from the customer portal.
apache-camel-${camel.version}.zip
found in Red Hat JBoss Fuse's extras/
directory:
user@example modules] unzip /path/to/jboss-fuse-${fuse.version}/extras/apache-camel-${camel.version}
Procedure 5.7. Add in the Camel components from JBoss Fuse
- Create a directory under $EAP_HOME/modules:
user@example jboss-eap-6.4]
cd modules
user@example modules]mkdir -p org/apache/camel/core
- Create a
main
subdirectory to store the jars:user@example modules]
mkdir org/apache/camel/core/main
- Copy over the camel-core jar from
apache-camel-${camel.version}.zip
to the newly createdmain
directory:user@example modules]
cp /path/to/jboss/fuse/extras/apache-camel-${camel.version}/lib/camel-core-${camel.version}.jar ./org/apache/camel/core/main/
- Create the
module.xml
descriptor by adding in the following text toorg/apache/camel/core/main/module.xml
:<?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.1" name="org.apache.camel.core"> <resources> <resource-root path="camel-core-${camel.version}.jar"/> </resources> </module>
- Repeat the above steps to create a module for each dependency in use; note that modules may have dependencies on other modules as described in the Red Hat JBoss Administration and Configuration Guide.
Procedure 5.8. Add in Camel components from JBoss Data Grid
- Create a
main
subdirectory for the JDG Camel components:user@example jboss-eap-6.4]
mkdir -p modules/org/apache/camel/main
- Unzip
jboss-datagrid-${jdg.version}-camel-library.zip
. - Copy
camel-jbossdatagrid-${jdg.version}.jar
into the newly created directory:user@example jboss-eap-6.4]
cp jboss-datagrid-${jdg.version}-camel-library/camel-jbossdatagrid-${jdg.version}.jar modules/org/apache/camel/main/
- Create a
module.xml
descriptor by adding in the following text toorg/apache/camel/main/module.xml
:<?xml version="1.0" encoding="UTF-8"?> <module xmlns="urn:jboss:module:1.1" name="org.apache.camel"> <resources> <resource-root path="camel-jbossdatagrid-${jdg.version}.jar"/> </resources> <dependencies> <module name="org.apache.camel.core" /> </dependencies> </module>
jboss-deployment-structure.xml
in the WEB-INF
of the war, and add dependencies on the newly created module:
<?xml version="1.0" encoding="UTF-8"?> <jboss-deployment-structure> <deployment> <dependencies> <module name="org.apache.camel" meta-inf="import"/> <!-- Add the following lines if Library mode is used --> <module name="org.infinispan" slot="jdg-7.0" /> <module name="org.jgroups" slot="jdg-7.0" /> <!-- Add the following lines if Remote Client-Server mode is used --> <module name="org.infinispan.client.hotrod" slot="jdg-7.0" /> </dependencies> </deployment> </jboss-deployment-structure>
Part IV. Running Red Hat JBoss Data Grid
Chapter 6. Run Red Hat JBoss Data Grid JAR Files with Maven
6.1. Run JBoss Data Grid (Remote Client-Server Mode)
Add the following dependencies to the pom.xml
file:
- Add
infinispan-remote
dependency:<dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-remote</artifactId> <version>${infinispan.version}</version> </dependency>
- For instances where a
Remote Cache Store
is in use also add theinfinispan-embedded
dependency as shown below:<dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-embedded</artifactId> <version>${infinispan.version}</version> </dependency>
- For instances where
JSR-107
is in use, ensure that thecache-api
packages are available at runtime. Having these packages available can be accomplished by any of the following methods:- Option 1: If JBoss EAP is in use, then add the JBoss Data Grid modules to this instance as described in Section 4.2, “Deploy JBoss Data Grid in JBoss EAP (Remote Client-Server Mode)”.Add the javax.cache.api module to the application's
jboss-deployment-structure.xml
. An example is shown below:<jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.2"> <deployment> <dependencies> <module name="javax.cache.api" slot="jdg-7.0" services="export"/> </dependencies> </deployment> </jboss-deployment-structure>
- Option 2: Download the
jboss-datagrid-${jdg.version}-library
file from the customer portal.Extract the downloaded archive.Embed thejboss-datagrid-${jdg.version}-library/lib/cache-api-${jcache.version}.jar
file into the desired application. - Option 3: If the JBoss Data Grid Maven repository is available then add an explicit dependency to the
pom.xml
of the project as seen below:<dependency> <groupId>javax.cache</groupId> <artifactId>cache-api</artifactId> <version>${jcache.version}</version> </dependency>
Warning
infinispan-embedded-query.jar
file. Do not include other versions of Hibernate Search and Lucene in the same deployment as infinispan-embedded-query
. This action will cause classpath conflicts and result in unexpected behavior.
6.2. Run JBoss Data Grid (Library Mode)
Note
Add the following dependencies to the pom.xml
file:
- Add
infinispan-embedded
dependency:<dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-embedded</artifactId> <version>${infinispan.version}</version> </dependency>
Add the following dependencies to the pom.xml
file:
- Add
infinispan-embedded-query
dependency:<dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-embedded-query</artifactId> <version>${infinispan.version}</version> </dependency>
Warning
infinispan-embedded-query.jar
file. Do not include other versions of Hibernate Search and Lucene in the same deployment as infinispan-embedded-query
. This action will cause classpath conflicts and result in unexpected behavior.
Chapter 7. Run Red Hat JBoss Data Grid in Remote Client-Server Mode
7.1. Prerequisites
- Ensure an appropriate version of OpenJDK is installed. For more information, see Section 2.3, “Install OpenJDK on Red Hat Enterprise Linux”
- Download and install the latest version of JBoss Data Grid. For more information, see Section 2.4.1, “Download Red Hat JBoss Data Grid”
7.2. Run Red Hat JBoss Data Grid in Standalone Mode
$JDG_HOME/bin/standalone.sh
$JDG_HOME/standalone/configuration/
standalone.xml
file.
7.3. Run Red Hat JBoss Data Grid in Clustered Mode
$JDG_HOME/bin/standalone.sh -c clustered.xml
$JDG_HOME/standalone/configuration/
clustered.xml
file.
7.4. Run Red Hat JBoss Data Grid in a Managed Domain
$JDG_HOME/bin/domain.sh
$JDG_HOME/domain/configuration/
domain.xml
and $JDG_HOME/domain/configuration/host.xml
files.
7.5. Run Red Hat JBoss Data Grid with a Custom Configuration
$JDG_HOME/standalone/configuration
directory.
$JDG_HOME/bin/standalone.sh -c ${FILENAME}
-c
used for this script does not allow absolute paths, therefore the specified file must be available in the $JDG_HOME/standalone/configuration
directory.
-c
parameter, JBoss Data Grid uses the default configuration.
domain.xml
and host.xml
by default, there are two separate flags for specifying custom configuration files.
-c
parameter as described above, and demonstrated in the following command:
$JDG_HOME/bin/domain.sh -c ${FILENAME}
--host-config
parameter, as demonstrated in the following command:
$JDG_HOME/bin/domain.sh --host-config=${FILENAME}
7.6. Set an IP Address to Run Red Hat JBoss Data Grid
127.0.0.1/localhost
. Use the -b
parameter with the script to specify an IP address.
$JDG_HOME/bin/standalone.sh -b ${IP_ADDRESS}
$JDG_HOME/bin/domain.sh -b ${IP_ADDRESS}
7.7. Running Red Hat JBoss Data Grid
- Use the following command to run JBoss Data Grid using the configuration defined in the
standalone.xml
file (located at$JDG_HOME/standalone/configuration
):$JDG_HOME/bin/standalone.sh
- Use the following command with an appended
-c
followed by the configuration file name to run JBoss Data Grid with a non-default configuration file:$JDG_HOME/bin/standalone.sh -c clustered.xml
- Use the following command to run JBoss Data Grid using the configuration defined in the
domain.xml
andhost.xml
files (located at$JDG_HOME/domain/configuration/
):$JDG_HOME/bin/domain.sh
Chapter 8. Run a Red Hat JBoss Data Grid as a Node without Endpoints
8.1. Benefits of a Node Without Endpoints
8.2. Sample Configuration for a Node without Endpoints
Procedure 8.1. Find the JBoss Data Grid Sample Configuration for a Node Without Endpoints
Extract the JBoss Data Grid ZIP
1. Extract the ZIP file for JBoss Data Grid Remote Client-Server mode. This is namedjboss-datagrid-server-${version}
. Add the relevant version to the file name.Navigate to the Appropriate Folder
In the extracted folder, navigate to the$JDG_HOME/docs/examples/config
folder.Find the Configuration Sample File
View theclustered-storage-only.xml
file, which contains the configuration for a node with no endpoints.
8.3. Configure a Node with No Endpoints
- Remove the
datagrid
subsystem. - Remove the
modcluster
subsystem. - Remove the
datasource
definition. - Remove
socket-bindings
formod_cluster
,Hot Rod
andmemcached
.
Chapter 9. Run Red Hat JBoss Data Grid in Library Mode
- As a prerequisite for the subsequent chapters, set up a new project using the instructions in Section 9.1, “Create a New Red Hat JBoss Data Grid Project”.
- Next, use JBoss Data Grid either as an embedded cache (see Chapter 10, Run Red Hat JBoss Data Grid in Library Mode (Single-Node Setup) for more information) or as a clustered cache (see Chapter 11, Run Red Hat JBoss Data Grid in Library Mode (Multi-Node Setup). Each tutorial is based on an Infinispan quickstart.
- Finally, monitor Red Hat JBoss EAP applications using JBoss Data Grid using the instructions in Chapter 12, Monitor Red Hat JBoss Data Grid Applications in Red Hat JBoss EAP
9.1. Create a New Red Hat JBoss Data Grid Project
9.2. Add Dependencies to Your Project
pom.xml
file, located in the Maven repository folder:
<dependency> <groupId>org.infinispan</groupId> <artifactId>infinispan-embedded</artifactId> <version>$VERSION</version> </dependency>
Note
version
value with the appropriate version of the libraries included in JBoss Data Grid.
9.3. Add a Profile to Your Project
settings.xml
file in $HOME/.m2/settings.xml
as follows:
Example 9.1. Adding a Profile
<profiles> <!-- Configure the JBoss GA Maven repository --> <profile> <id>jboss-ga-repository</id> <repositories> <repository> <id>jboss-ga-repository</id> <url>http://maven.repository.redhat.com/techpreview/all</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>jboss-ga-plugin-repository</id> <url>http://maven.repository.redhat.com/techpreview/all</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> </profile> <!-- Configure the JBoss Early Access Maven repository --> <profile> <id>jboss-earlyaccess-repository</id> <repositories> <repository> <id>jboss-earlyaccess-repository</id> <url>http://maven.repository.redhat.com/earlyaccess/all/</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>jboss-earlyaccess-plugin-repository</id> <url>http://maven.repository.redhat.com/earlyaccess/all/</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </pluginRepository> </pluginRepositories> </profile> </profiles> <!-- Add active profiles information here -->
settings.xml
file:
Example 9.2. Enable the Profile
<activeProfiles> <!-- Optionally, make the repositories active by default --> <activeProfile>jboss-ga-repository</activeProfile> <activeProfile>jboss-earlyaccess-repository</activeProfile> </activeProfiles>
client/java/
directory, included in the Red Hat JBoss Data Grid package to the build classpath.
Chapter 10. Run Red Hat JBoss Data Grid in Library Mode (Single-Node Setup)
10.1. Run the Quickstart Class
These quickstarts use the Infinispan quickstarts located at https://github.com/infinispan/infinispan-quickstart. The following procedure uses the infinispan-quickstart/embedded-cache
quickstart.
Procedure 10.1. Run the Quickstart Class
Open the Quickstart.java File
Open the file calledQuickstart.java
in theinfinispan-quickstart/embedded-cache
.Add the Quickstart Class
Examining theQuickstart.java
file we can see that this class creates aDefaultCacheManager
and then obtains a local reference to thedefault
cache, as no cache name is specified:package org.infinispan.quickstart.embeddedcache; import org.infinispan.Cache; import org.infinispan.manager.DefaultCacheManager; public class Quickstart { public static void main(String args[]) throws Exception { Cache<Object, Object> c = new DefaultCacheManager().getCache(); } }
Copy Dependencies and Compile Java Classes
Use the following command to copy all project dependencies to a directory and compile the Java classes from your project:$ mvn clean compile dependency:copy-dependencies -DstripVersion
Run the Main Method
Use the following command to run the main method:$ java -cp target/classes/:target/dependency/* package org.infinispan.quickstart.embeddedcache.Quickstart
10.2. Use the Default Cache
10.2.1. Add and Remove Data from the Cache
Procedure 10.2. Add and Remove Data from the Cache
- Add an entry, replacing key and value with the desired key and value:
cache.put("key", "value");
- Confirm that the entry is present in the cache:
assertEquals(1, cache.size()); assertTrue(cache.containsKey("key"));
- Remove the entry from the cache:
Object v = cache.remove("key");
- Confirm that the entry is no longer present in the cache:
assertEquals("value", v); assertTrue(cache.isEmpty());
10.2.2. Adding and Replacing a Key Value
DefaultCacheQuickstart.java
file does:
Procedure 10.3. Adding and Replacing a Key Value
- Add an entry
key
withvalue
as the key's value.cache.put("key", "value");
Procedure 10.4. Replacing a Key Value
- The following code searches for keys (named
key
andkey2
). If the two specific keys beings searched for are not found, JBoss Data Grid creates two new keys with the specified key names and values.cache.putIfAbsent("key", "newValue"); cache.putIfAbsent("key2", "value2");
- The following code confirms that the value of the stored key equals the value we wanted to store.
assertEquals(cache.get("key"), "value"); assertEquals(cache.get("key2"), "value2");
See Also:
10.2.3. Removing Entries
All of the following methods are found on org.infinispan.Cache
and its subclasses.
remove(key)
- remove a single key from the cache.removeAsync(key)
- remove a single key from the cache, asynchronously.clear()
- removes all of the mappings from the cache, leaving it empty once the call completes.clearAsync()
- asynchronously remove all of the mappings from the cache, leaving it empty once the call completes.cache.evict(key)
- remove the entry from the cache, moving it to the cache store if one is defined. With no cache store defined the entry is removed from the cache and is lost.
All of the following methods are found on org.infinispan.client.hotrod.RemoteCache
and its subclasses.
remove(key)
- remove a single key from the cache.removeAsync(key)
- remove a single key from the cache, asynchronously.clear()
- removes all of the mappings from the cache, leaving it empty once the call completes.clearAsync()
- asynchronously remove all of the mappings from the cache, leaving it empty once the call completes.removeWithVersion(key, version)
- remove a single key from the cache only if its current version matches the supplied version.removeWithVersionAsync(key, value)
- asynchronously remove a single key from the cache only if its current version matches the supplied version.
10.2.4. Placing and Retrieving Sets of Data
AdvancedCache
and RemoteCache
interfaces include methods to either put or get a Map
of existing data in bulk. These operations are typically much more efficient than an equivalent sequence of individual operations, especially when using them in server-client mode, as a single network operation occurs as opposed to multiple transactions.
get
or put
operation must accommodate for the full Map
in a single execution.
AdvancedCache
:Map<K,V>
getAll(Set<?> keys)
- returns aMap
containing the values associated with the set of keys requested.- void
putAll(Map<? extends K, ? extends V> map, Metadata metadata)
- copies all of the mappings from the specified map to this cache, which takes an instance ofMetadata
to provide metadata information such as the lifespan, version, etc. on the entries being stored.
RemoteCache
:Map<K,V>
getAll(Set<? extends K> keys)
- returns aMap
containing the values associated with the set of keys requested.- void
putAll(Map<? extends K, ? extends V> map)
- copies all of the mappings from the specified map to this cache. - void
putAll(Map<? extends K, ? extends V> map, long lifespan, TimeUnit unit)
- copies all of the mappings from the specified map to this cache, along with a lifespan before the entry is expired. - void
putAll(Map<? extends K, ? extends V> map, long lifespan, TimeUnit lifespanUnit, long maxIdleTime, TimeUnit maxIdleTimeUnit)
- copies all of the mappings from the specified map to this cache, along with both a timespan before the entries are expired and the maximum amount of time the entry is allowed to be idle before it is considered to be expired.
10.2.5. Adjust Data Life
DefaultCacheQuickstart.java
file does:
Procedure 10.5. Adjust the Data Life
- Alter the key's
lifespan
value:cache.put("key", "value", 5, TimeUnit.SECONDS);
- Check if the cache contains the key:
assertTrue(cache.containsKey("key"));
- After the allocated
lifespan
time has expired, the key is no longer in the cache:Thread.sleep(10000); assertFalse(cache.containsKey("key"));
10.2.6. Default Data Mortality
10.2.7. Register the Named Cache Using XML
infinispan.xml
file.
infinispan.xml
file is located in https://github.com/jboss-developer/jboss-jdg-quickstarts/ within the secure-embedded-cache/src/main/resources/
folder, and the full schema is available in the docs/schema/
directory of the Red Hat JBoss Data Grid Library distribution.
Chapter 11. Run Red Hat JBoss Data Grid in Library Mode (Multi-Node Setup)
11.1. Sharing JGroup Channels
Example 11.1. Shared JGroups Channel
EmbeddedCacheManager cm = $LOCATION Cache<Object, Object> cache1 = cm.getCache("replSyncCache"); Cache<Object, Object> cache2 = cm.getCache("replAsyncCache"); Cache<Object, Object> cache3 = cm.getCache("invalidationSyncCache");
11.2. Run Red Hat JBoss Data Grid in a Cluster
11.2.1. Compile the Project
$ mvn clean compile dependency:copy-dependencies -DstripVersion
11.2.2. Run the Clustered Cache with Replication Mode
Procedure 11.1. Run the Clustered Cache with Replication Mode
- Use the following command to launch the first node:
$ java -cp target/classes/:target/dependency/* org.infinispan.quickstart.clusteredcache.replication.Node0
- Use the following command to launch the second node:
$ java -cp target/classes/:target/dependency/* org.infinispan.quickstart.clusteredcache.replication.Node1
JGroups and JBoss Data Grid initialized on both nodes. After approximately fifteen seconds, the cache entry log message appears on the console of the first node.
11.2.3. Run the Clustered Cache with Distribution Mode
Procedure 11.2. Run the Clustered Cache with Distribution Mode
- Use the following command to launch the first node:
$ java -cp target/classes/:target/dependency/* org.infinispan.quickstart.clusteredcache.distribution.Node0
- Use the following command to launch the second node:
$ java -cp target/classes/:target/dependency/* org.infinispan.quickstart.clusteredcache.distribution.Node1
- Use the following command to launch the third node:
$ java -cp target/classes/:target/dependency/* org.infinispan.quickstart.clusteredcache.distribution.Node2
JGroups and JBoss Data Grid initialized on the three nodes. After approximately fifteen seconds, the ten entries added by the third node are visible as they are distributed to the first and second nodes.
11.2.4. Configure the Cluster
Procedure 11.3. Configure the Cluster
- Add the default configuration for a new cluster.
- Customize the default cluster configuration according to the requirements of your network. This is done declaratively (using XML) or programmatically.
- Configure the replicated or distributed data grid.
11.2.4.1. Add the Default Cluster Configuration
Example 11.2. Default Configuration
new ConfigurationBuilder() .clustering().cacheMode(CacheMode.REPL_SYNC) .build()
Note
GlobalConfigurationBuilder().clusteredDefault()
to quickly create a preconfigured and cluster-aware GlobalConfiguration
for clusters. This configuration can also be customized.
11.2.4.2. Customize the Default Cluster Configuration
Use the following GlobalConfiguration code to specify the name of the file to use for JGroups configuration:
new GlobalConfigurationBuilder().transport().addProperty("configurationFile", "jgroups.xml") .build()
jgroups.xml
with the desired file name.
jgroups.xml
file is located at Infinispan-Quickstart/clustered-cache/src/main/resources/
.
Note
-Djgroups.bind_addr="127.0.0.1"
. This is particularly useful to test a cluster where all nodes are on a single machine.
Use the following XML snippet in the infinispan.xml
file to configure the JGroups properties to use Red Hat JBoss Data Grid's XML configuration:
<global> <transport> <properties> <property name="configurationFile" value="jgroups.xml"/> </properties> </transport> </global>
11.2.4.3. Configure the Replicated Data Grid
Use the following code snippet to programmatically configure the cache for replication mode (either synchronous or asynchronous):
private static EmbeddedCacheManager createCacheManagerProgramatically() { return new DefaultCacheManager( new GlobalConfigurationBuilder() .transport().addProperty("configurationFile", "jgroups.xml") .build(), new ConfigurationBuilder() .clustering().cacheMode(CacheMode.REPL_SYNC) .build() ); }
Edit the infinispan.xml
file to include the following XML code to declaratively configure the cache for replication mode (either synchronous or asynchronous):
<infinispan xsi:schemaLocation="urn:infinispan:config:8.3 http://www.infinispan.org/schemas/infinispan-config-8.3.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:infinispan:config:8.3"> <global> <transport> <properties> <property name="configurationFile" value="jgroups.xml"/> </properties> </transport> </global> <default> <clustering mode="replication"> <sync/> </clustering> </default> </infinispan>
private static EmbeddedCacheManager createCacheManagerFromXml() throws IOException { return new DefaultCacheManager("infinispan.xml");}
Note
org.infinispan.jmx.JmxDomainConflictException: Domain already registered org.infinispan
.
GlobalConfiguration glob = new GlobalConfigurationBuilder() .clusteredDefault() .globalJmxStatistics() .allowDuplicateDomains(true) .enable() .build();
11.2.4.4. Configure the Distributed Data Grid
numOwners
parameter, which sets how many owners each entry has.
numOwners
value to set the desired trade off between space, durability and availability. Durability is further improved by JBoss Data Grid's topology aware consistent hash, which locates entry owners across a variety of data centers, racks and nodes.
Programmatically configure the cache for distributed mode (either synchronous or asynchronous) as follows:
new ConfigurationBuilder() .clustering() .cacheMode(CacheMode.DIST_SYNC) .hash().numOwners(2) .build()
Edit the infinispan.xml
file to include the following XML code to declaratively configure the cache for distributed mode (either synchronous or asynchronous):
<default> <clustering mode="distribution"> <sync/> <hash numOwners="2"/> </clustering> </default>
Chapter 12. Monitor Red Hat JBoss Data Grid Applications in Red Hat JBoss EAP
12.1. Prerequisites
- Install and configure JBoss Enterprise Application Platform 6 (or better).
- Install and configure JBoss Operations Network 3.2.2 (or better).
- Install and configure JBoss Data Grid (6.3 or better) Library mode plug-in.
12.2. Monitor Red Hat JBoss Data Grid Applications in Red Hat JBoss EAP
Procedure 12.1. Monitor JBoss Data Grid Applications in JBoss Enterprise Application Platform
Configure RHQ/JBoss Operations Network
Add an RHQ/JBoss Operations Network specific property (namedorg.rhq.resourceKey
) to the/bin/
standalone.conf
file as follows:JAVA_OPTS="$JAVA_OPTS -Dorg.rhq.resourceKey=MyEAP"
This command adds the property to the JBoss Enterprise Application Platform's command line indirectly.Check RHQ/JBoss Operations Network is Running Using a Full JDK
Ensure that the RHQ/JBoss Operations Network agent started using a full JDK instead of a JRE. This is because the agent requires access to the JDK'stools.jar
file.To configure your RHQ/JBoss Operations Network agent to use the JDK, follow the instructions relevant to your operating system:- For Linux users, set the
RHQ_AGENT_JAVA_HOME
environment variable to the JDK home directory in the agent'srhq-agent-env.sh
file. - For Windows users, set the
RHQ_AGENT_JAVA_HOME
environment variable to the JDK home directory in the agent'srhq-agent-env.bat
file.
Ensure the Agent is Local to the JBoss Enterprise Application Platform Instance
Ensure that the RHQ/JBoss Operations Network agent runs locally to and under the same user as the JBoss Application Platform instance. This is required for the Java Attach API to connect to the process.Import Resources to the Agent Inventory
RHQ/JBoss Operations Network can now discover resources. These resources can subsequently be imported into the agent inventory.When a JBoss Data Grid user deployment enables JMX statistics to expose JBoss Data Grid Cache Managers or caches, the resources appear as children resources of the JBoss Enterprise Application Platform instance.
Part V. Set Up a Cache Manager
Chapter 13. Cache Managers
- it creates cache instances on demand.
- it retrieves existing cache instances (i.e. caches that have already been created).
13.1. Types of Cache Managers
EmbeddedCacheManager
is a cache manager that runs within the Java Virtual Machine (JVM) used by the client. Currently, JBoss Data Grid offers only theDefaultCacheManager
implementation of theEmbeddedCacheManager
interface.RemoteCacheManager
is used to access remote caches. When started, theRemoteCacheManager
instantiates connections to the Hot Rod server (or multiple Hot Rod servers). It then manages the persistentTCP
connections while it runs. As a result,RemoteCacheManager
is resource-intensive. The recommended approach is to have a singleRemoteCacheManager
instance for each Java Virtual Machine (JVM).
13.2. Creating CacheManagers
13.2.1. Create a New RemoteCacheManager
Procedure 13.1. Configure a New RemoteCacheManager
import org.infinispan.client.hotrod.RemoteCache; import org.infinispan.client.hotrod.RemoteCacheManager; import org.infinispan.client.hotrod.configuration.Configuration; import org.infinispan.client.hotrod.configuration.ConfigurationBuilder; Configuration conf = new ConfigurationBuilder().addServer().host("localhost").port(11222).build(); RemoteCacheManager manager = new RemoteCacheManager(conf); RemoteCache defaultCache = manager.getCache();
- Use the
ConfigurationBuilder()
constructor to create a new configuration builder. The.addServer()
method adds a remote server, configured via the.host(<hostname|ip>)
and.port(<port>)
properties. - Create a new
RemoteCacheManager
using the supplied configuration. - Retrieve the default cache from the remote server.
13.2.2. Create a New Embedded Cache Manager
Procedure 13.2. Create a New Embedded Cache Manager
- Create a configuration XML file. For example, create the
my-config-file.xml
file on the classpath (in theresources/
folder) and add the configuration information in this file. - Use the following programmatic configuration to create a cache manager using the configuration file:
EmbeddedCacheManager manager = new DefaultCacheManager("my-config-file.xml"); Cache defaultCache = manager.getCache();
my-config-file.xml
.
13.2.3. Create a New Embedded Cache Manager Using CDI
Procedure 13.3. Use CDI to Create a New EmbeddedCacheManager
- Specify a default configuration:
public class Config @Produces public EmbeddedCacheManager defaultCacheManager() { ConfigurationBuilder builder = new ConfigurationBuilder(); Configuration configuration = builder.eviction().strategy(EvictionStrategy.LRU).maxEntries(100).build(); return new DefaultCacheManager(configuration); } }
- Inject the default cache manager.
<!-- Additional configuration information here --> @Inject EmbeddedCacheManager cacheManager; <!-- Additional configuration information here -->
13.3. Multiple Cache Managers
13.3.1. Create Multiple Caches with a Single Cache Manager
13.3.2. Using Multiple Cache Managers
TCP
protocol and the other uses the UDP
protocol, multiple cache managers must be used.
13.3.3. Create Multiple Cache Managers
infinispan.xml
file to a new configuration file. Edit the new file for the desired configuration and then use the new file for a new cache manager.
Part VI. Red Hat JBoss Data Grid Quickstarts
Chapter 14. The Hello World Quickstart
- from a servlet.
- from a JSF page using request scoped beans.
Important
JBoss Data Grid's Hello World quickstart is available at the following location: jboss-datagrid-{VERSION}-quickstarts/
14.1. Quickstart Prerequisites
- Java 8.0 (Java SDK 1.8) or better
- JBoss Enterprise Application Platform 7.x or JBoss Enterprise Web Server 3.x
- Maven 3.0 or better
- Configure the Maven Repository. For details, see Chapter 3, Install and Use the Maven Repositories
14.2. Start Two Application Server Instances
Procedure 14.1. Start the First Application Server Instance
Navigate to the Root Directory
In the command line terminal, navigate to the root for your JBoss server directory.Start the First Application Server
Depending on your operating system, use the appropriate command from the following to start the first instance of your selected application server:- For Linux:
$JBOSS_HOME/bin/standalone.sh
- For Windows:
$JBOSS_HOME\bin\standalone.bat
Procedure 14.2. Start the Second Application Server Instance
Clone the Application Server
Create a copy of the selected JBoss Server to create a second instance.Navigate to the Root Directory
In the command line terminal, navigate to the root for your JBoss server directory.Start the Second Application Server
Use the appropriate command for your operating system from the following commands. This command starts the server with the provided port offset to ensure that both the server instances run on the same host.- For Linux:
$JBOSS_HOME2/bin/standalone.sh -Djboss.socket.binding.port-offset=100
- For Windows:
$JBOSS_HOME2\bin\standalone.bat -Djboss.socket.binding.port-offset=100
14.3. Build and Deploy the Hello World Quickstart
Procedure 14.3. Build and Deploy the Hello World Quickstart
Navigate to the Required Directory
In the command line terminal, navigate to the root directory of the quickstart on the command line interface.Build and Deploy to the First Application Server Instance
Use the following command to build and deploy the quickstart to the first application server instance as follows:# mvn clean package wildfly:deploy
This command deploystarget/
jboss-helloworld-jdg.war
to the first running server instance.Build and Deploy to the Second Application Server Instance
Use the following command to build and deploy the quickstart to the second application server instance with the specified ports as follows:# mvn clean package wildfly:deploy -Dwildfly.port=10090
This command deploystarget/
jboss-helloworld-jdg.war
to the second running server instance.
14.4. Access the Running Application
- First Server Instance: http://localhost:8080/jboss-helloworld-jdg
- Second Server Instance: http://localhost:8180/jboss-helloworld-jdg
14.5. Test Replication on the Application
Procedure 14.4. Test Replication on the Application
Access the First Server
Access the first application server and enter the key and value.- Access the first application server in a browser window using the following URL:
http://localhost:8080/jboss-helloworld-jdg
- Insert the key
foo
. - Insert the value
bar
.
Access the Second Server
Access the second application server and enter the key and value.- Access the second application server in a browser window using the following URL:
http://localhost:8180/jboss-helloworld-jdg
- Click.
- Get the key
foo
. - Click.
- Insert the key
mykey
. - Insert the value
myvalue
.
Get All Keys and Values
Access the first server and request all keys.- Access the first application server in a browser window using the following URL:
http://localhost:8080/jboss-helloworld-jdg
- Click.
- Clickto request all key and values.
As the results of the last step show, all the data added at each server has been replicated to the other server.
Note
60
seconds from the most recent update.
To interact with predefined servlets or to directly store and retrieve keys from the cache, use the following URLs:
http://localhost:8080/jboss-helloworld-jdg/TestServletPut
http://localhost:8180/jboss-helloworld-jdg/TestServletGet
14.6. Remove the Application
Procedure 14.5. Remove the Application
Start the Application Servers
Ensure that both server instances are running.Navigate to the Root
In the command line terminal, navigate to the root directory of the quickstart.Remove the Archive
Use the following commands to remove the archive from both the server instances.- Remove the archive from the first server as follows:
mvn wildfly:undeploy
- Remove the archive from the second server as follows:
mvn wildfly:undeploy -Dwildfly.port=10090
Chapter 15. The CarMart Quickstarts
The CarMart quickstart offers the following features:
- List all cars
- Add new cars
- Remove cars
- View statistics for caches, such as hits, stores, and retrievals
The CarMart quickstart can be used in the following JBoss Data Grid usage modes:
- Remote Client-Server Mode, where the application includes the Hot Rod client to communicate with a remote JBoss Data Grid server.
- Library Mode, where all libraries are bundled with the application in the form of
jar
files.
JBoss Data Grid's CarMart quickstart is available at the following location: jboss-datagrid-{VERSION}-quickstarts/
15.1. About the CarMart Transactional Quickstart
The Transactional CarMart Quickstart offers the following features:
- List all cars
- Add new cars
- Add new cars with rollback
- Remove cars
- View statistics for caches, such as hits, stores, and retrievals
The Transactional CarMart Quickstart can only be used in JBoss Data Grid's Library mode. A standalone transaction manager from JBoss Transactions is used when the Transactional CarMart Quickstart is run in Red Hat JBoss Enterprise Web Server 2.x.
JBoss Data Grid's Transactional CarMart Quickstart can be found at the following location: jboss-datagrid-{VERSION}-quickstarts/carmart-tx
15.2. Differences Between the CarMart and Transactional Quickstarts
- CarMart is available for both Remote Client-Server Mode and Library Mode. Transactional CarMart is only available in Library Mode because transactions are not available in Remote Client-Server Mode.
- The Transactional Quickstart also displays how a transaction rollback occurs. Use thebutton to view the rollback. The CarMart example has a simple button instead.
15.3. The (Non-transactional) CarMart Quickstart Using JBoss EAP
15.3.1. Quickstart Prerequisites
- Java 8.0 (Java SDK 1.8) or better
- JBoss Enterprise Application Platform 7.x or JBoss Enterprise Web Server 3.x
- Maven 3.0 or better
- Configure the Maven Repository. For details, see Chapter 3, Install and Use the Maven Repositories
15.3.2. Build and Deploy the CarMart Quickstart to JBoss EAP
Prerequisites for this procedure are as follows:
- Obtain the supported JBoss Data Grid Library Mode distribution files.
- Ensure that the JBoss Data Grid and JBoss Enterprise Application Platform Maven repositories are installed and configured. For details, see Chapter 3, Install and Use the Maven Repositories
- Select a JBoss server to use (JBoss Enterprise Application Platform 7 or better).
Procedure 15.1. Build and Deploy CarMart to JBoss EAP
Start JBoss EAP
Depending on your operating system, use the appropriate command from the following to start the first instance of your selected application server:For Linux users:$JBOSS_HOME/bin/standalone.sh
For Windows users:$JBOSS_HOME\bin\standalone.bat
Navigate to the Root Directory
Open a command line and navigate to the root directory of this quickstart.Build and Deploy the Application
Use the following command to build and deploy the application using Maven:$ mvn clean package wildfly:deploy
The target war file (target/
jboss-carmart.war
) is deployed to the running instance of JBoss EAP.
15.3.3. View the CarMart Quickstart on JBoss EAP
The CarMart quickstart must be built and deployed to be viewed.
Procedure 15.2. View the CarMart Quickstart on JBoss EAP
- To view the application, use your browser to navigate to the following link:
http://localhost:8080/jboss-carmart
15.3.4. Remove the CarMart Quickstart from JBoss EAP
Procedure 15.3. Remove an Application from JBoss EAP
- To remove an application, use the following from the root directory of this quickstart:
$ mvn wildfly:undeploy
15.4. The (Non-transactional) CarMart Quickstart Using JBoss Enterprise Web Server
15.4.1. Build and Deploy the CarMart Quickstart to JBoss Enterprise Web Server
Prerequisites for this procedure are as follows:
- Ensure that the JBoss Data Grid and JBoss Enterprise Application Platform Maven repositories are installed and configured. For details, see Chapter 3, Install and Use the Maven Repositories
- Select JBoss Enterprise Web Server 3 (or better) for your application and install it.
Procedure 15.4. Build the CarMart Quickstart to the Server (Library Mode)
Start the Server
Depending on your operating system, use the appropriate command from the following to start the first instance of your selected application server:For Linux users:$JBOSS_EWS_HOME/tomcat8/bin/catalina.sh run
For Windows users:$JBOSS_EWS_HOME\tomcat8\bin\catalina.bat run
Navigate to the Root Directory
Open a command line and navigate to the root directory of this quickstart.Build and Deploy your Application
Use the following command to build and deploy your application using Maven:$ mvn -Plibrary-tomcat clean package tomcat:deploy
The target war file (target/
jboss-carmart.war
) is deployed to the running instance of the selected server.
15.4.2. View the CarMart Quickstart Using JBoss Enterprise Web Server
The CarMart quickstart must be built and deployed to be viewed.
Procedure 15.5. View the CarMart Quickstart
- To view the application, use your browser to navigate to the following link:
http://localhost:8080/jboss-carmart
15.4.3. Remove the CarMart Quickstart from JBoss Enterprise Web Server
Procedure 15.6. Remove an Application from JBoss Enterprise Web Server
- To remove an application, use the following command from the root directory of this quickstart:
$ mvn -Plibrary-tomcat tomcat:undeploy
15.5. The (Non-transactional) CarMart Quickstart in Remote Client-Server Mode (JBoss EAP)
15.5.1. Build and Deploy the CarMart Quickstart in Remote Client-Server Mode
Important
Prerequisites for this procedure are as follows:
- Obtain the most recent supported JBoss Data Grid Remote Client-Server Mode distribution files from Red Hat.
- Ensure that the JBoss Data Grid and JBoss Enterprise Application Platform Maven repositories are installed and configured. For details, see Chapter 3, Install and Use the Maven Repositories
- Select a JBoss server to use (JBoss Enterprise Application Platform 7 or later). Navigate to the root of the JBoss server directory in a terminal window and enter the following command:For Linux users:
$JBOSS_HOME/bin/standalone.sh
For Windows users:$JBOSS_HOME\bin\standalone.bat
Procedure 15.7. Build and Deploy the CarMart Quickstart in Remote Client-Server Mode
Configure the Standalone File
Add the following configuration to thestandalone.xml
file located in the$JDG_HOME/standalone/configuration/
directory.- Add the following configuration within the infinispan subsystem tags, before the ending
cache-container
tag:<local-cache name="carcache" start="EAGER" batching="false" statistics="true"> <eviction strategy="LIRS" max-entries="4"/> </local-cache>
Note
If thecarcache
element already exists in your configuration, replace it with the provided configuration.
Start the JBoss Data Grid Server
Run the following script to start the JBoss Data Grid Server:$JDG_HOME/bin/
standalone.sh
-Djboss.socket.binding.port-offset=100Start the JBoss Server
Run the following script to start the JBoss server instance where your application will deploy:$JBOSS_HOME/bin/
standalone.sh
Optional: Specify the Host and Port Address
The application uses the values in thejboss-datagrid-{VERSION}-quickstarts/carmart/src/main/resources/META-INF/
datagrid.properties
file to locate the JBoss Data Grid server. If your JBoss Data Grid server is not running using the default host and port values, edit the file and insert the correct host and port values, as follows:datagrid.host=localhost datagrid.hotrod.port=11322
Navigate to the Root Directory
Open a command line and navigate to the root directory of this quickstart.Build and Deploy the Application
Use the following command to build and deploy your application using Maven:$ mvn clean package wildfly:deploy -Premote-eap
15.5.2. View the CarMart Quickstart in Remote Client-Server Mode
The CarMart quickstart must be built and deployed be viewed.
Procedure 15.8. View the CarMart Quickstart in Remote Client-Server Mode
- Visit the following link in a browser window to view the application:
http://localhost:8080/jboss-carmart
15.5.3. Remove the CarMart Quickstart in Remote Client-Server Mode
Procedure 15.9. Remove an Application in Remote Client-Server Mode
- To remove an application, use the following command from the root directory of this quickstart:
$ mvn wildfly:undeploy -Premote-eap
15.6. The (Non-Transactional) CarMart Quickstart in Remote Client-Server Mode (JBoss Enterprise Web Server)
15.6.1. Build and Deploy the CarMart Quickstart in Remote Client-Server Mode
Important
Prerequisites for this procedure are as follows:
- Obtain the most recent supported JBoss Data Grid Remote Client-Server Mode distribution files from Red Hat.
- Ensure that the JBoss Data Grid and JBoss Enterprise Application Platform Maven repositories are installed and configured. For details, see Chapter 3, Install and Use the Maven Repositories
- Add a
server
element to the Mavensettings.xml
file. In theid
elements withinserver
, add the appropriate tomcat credentials.<server> <id>tomcat</id> <username>admin</username> <password>admin</password> </server>
Procedure 15.10. Build and Deploy the CarMart Quickstart in Remote Client-Server Mode
Configure the Standalone File
Add the following configuration to thestandalone.xml
file located in the$JDG_HOME/standalone/configuration/
directory.- Add the following configuration within the infinispan subsystem tags:
<local-cache name="carcache" start="EAGER" batching="false" statistics="true"> <eviction strategy="LIRS" max-entries="4"/> </local-cache>
Note
If thecarcache
element already exists in your configuration, replace it with the provided configuration.
Start the Container
Start the JBoss server instance where your application will deploy.For Linux:$JBOSS_EWS_HOME/tomcat8/bin/catalina.sh run
For Windows:$JBOSS_EWS_HOME\tomcat8\bin\catalina.bat run
Build the Application
Use the following command to build your application in the relevant directory:$ mvn clean package -Premote-tomcat
Deploy the Application
Use the following command to deploy the application in the relevant directory:mvn tomcat:deploy -Premote-tomcat
15.6.2. View the CarMart Quickstart in Remote Client-Server Mode
The CarMart quickstart must be built and deployed be viewed.
Procedure 15.11. View the CarMart Quickstart in Remote Client-Server Mode
- Visit the following link in a browser window to view the application:
http://localhost:8080/jboss-carmart
15.6.3. Remove the CarMart Quickstart in Remote Client-Server Mode
Procedure 15.12. Remove an Application in Remote Client-Server Mode
- To remove an application, use the following command from the root directory of this quickstart:
$ mvn tomcat:undeploy -Premote-tomcat
15.7. The (Transactional) CarMart Quickstart Using JBoss EAP
JBossASCacheContainerProvider
/TomcatCacheContainerProvider
implementation classes for the CacheContainerProvider
interface.
15.7.1. Quickstart Prerequisites
- Java 8.0 (Java SDK 1.8) or better
- JBoss Enterprise Application Platform 7.x or JBoss Enterprise Web Server 3.x
- Maven 3.0 or better
- Configure the Maven Repository. For details, see Chapter 3, Install and Use the Maven Repositories
15.7.2. Build and Deploy the Transactional CarMart Quickstart
Ensure that the following prerequisites are met before building and deploying the CarMart quickstart.
- Configure Maven (See Section 15.7.1, “Quickstart Prerequisites”)
- Start JBoss Enterprise Application Platform:
- In a command line terminal, navigate to the root of the JBoss EAP server directory.
- Use one of the following commands to start the server with a web profile:For Linux:
$JBOSS_HOME/bin/standalone.sh
For Windows:%JBOSS_HOME%\bin\standalone.bat
Procedure 15.13. Build and Deploy the Transactional Quickstart
- Open a command line and navigate to the root directory of this quickstart.
- Enter the following command to build and deploy the archive:
mvn clean package wildfly:deploy
- The
target/jboss-carmart-tx.war
file is deployed to the running instance of the server.
15.7.3. View the Transactional CarMart Quickstart
The CarMart quickstart must be built and deployed to be viewed.
Procedure 15.14. View the CarMart Quickstart
- To view the application, use your browser to navigate to the following link:
http://localhost:8080/jboss-carmart-tx
15.7.4. Undeploy The Transactional CarMart Quickstart
- In a command line terminal, navigate to the root directory of the quickstart.
- Undeploy the archive as follows:
mvn wildfly:undeploy
15.7.5. Test the Transactional CarMart Quickstart
- Stop JBoss EAP, if it is running.
- In a command line terminal, navigate to root directory for the quickstart.
- Build the quickstarts as follows:
mvn clean package
- Run the tests as follows:
mvn test -Puitests-eap -Das7home=/path/to/server
15.8. The (Transactional) CarMart Quickstart Using JBoss Enterprise Web Server
library-tomcat
profile can be used when running this quickstart with JBoss Enterprise Web Server because this profile enables library mode.
15.8.1. Quickstart Prerequisites
- Java 8.0 (Java SDK 1.8) or better
- JBoss Enterprise Application Platform 7.x or JBoss Enterprise Web Server 3.x
- Maven 3.0 or better
- Configure the Maven Repository. For details, see Chapter 3, Install and Use the Maven Repositories
15.8.2. Build and Deploy the Transactional CarMart Quickstart
Ensure that the following prerequisites are met before building and deploying the CarMart quickstart.
- Configure Maven (See Section 15.8.1, “Quickstart Prerequisites”)
- To configure JBoss Enterprise Web Server, add the following lines to the
conf/tomcat-users.xml
file:<role rolename="manager-script"/> <user username="admin" password="admin" roles="manager-script"/>
- Configure Maven by adding the following configuration information to the Maven
settings.xml
file with the appropriate credentials:<server> <id>tomcat</id> <username>admin</username> <password>admin</password> </server>
- Start JBoss Enterprise Web Server:
- In a command line terminal, navigate to the root of the JBoss Enterprise Web Server directory.
- Use one of the following commands to start the server with a web profile:For Linux:
$TOMCAT_HOME/bin/catalina.sh run
For Windows:%TOMCAT_HOME%\bin\catalina.bat run
Procedure 15.15. Build and Deploy the Transactional CarMart Quickstart
- In a command line terminal, navigate to the root directory for the quickstart.
- Enter the following command to build and deploy archive:
mvn -Plibrary-tomcat clean package tomcat:deploy
- The
target/jboss-carmart-tx.war
file is deployed to the running instance of JBoss Enterprise Web Server.
15.8.3. View the Transactional CarMart Quickstart
The CarMart quickstart must be built and deployed to be viewed.
Procedure 15.16. View the CarMart Quickstart
- To view the application, use your browser to navigate to the following link:
http://localhost:8080/jboss-carmart-tx
15.8.4. Undeploy The Transactional CarMart Quickstart
- In a command line terminal, navigate to the root directory of the quickstart.
- Undeploy the archive as follows:
mvn -Plibrary-tomcat tomcat:undeploy
15.8.5. Test the Transactional CarMart Quickstart
- Undeploy the archive (see Section 15.8.4, “Undeploy The Transactional CarMart Quickstart”)
- Stop JBoss Enterprise Web Server, if it is running.
- In a command line terminal, navigate to root directory for the quickstart.
- Build the quickstarts as follows:
mvn clean package
- Run the tests as follows:
mvn test -Puitests-tomcat -Das7home=/path/to/server
Chapter 16. The Football Quickstart Endpoint Examples
The following features are available with the example Football Manager application:
- Add a team
- Add players
- Remove all entities (teams and players)
- Listing all teams and players
JBoss Data Grid's Football quickstart can be found at the following locations:
jboss-datagrid-{VERSION}-quickstarts/rest-endpoint
jboss-datagrid-{VERSION}-quickstarts/hotrod-endpoint
jboss-datagrid-{VERSION}-quickstarts/memcached-endpoint
16.1. Quickstart Prerequisites
- Java 8.0 (Java SDK 1.8) or better
- JBoss Enterprise Application Platform 7.x or JBoss Enterprise Web Server 3.x
- Maven 3.0 or better
- Configure the Maven Repository. For details, see Chapter 3, Install and Use the Maven Repositories
16.2. Build the Football Application
Important
Prerequisites for this procedure are as follows:
- Obtain the most recent supported JBoss Data Grid Remote Client-Server Mode distribution files from Red Hat.
- Ensure that the JBoss Data Grid and JBoss Enterprise Application Platform Maven repositories are installed and configured. For details, see Chapter 3, Install and Use the Maven Repositories
Procedure 16.1. Build the Football Application
Add Configurations
Edit thestandalone.xml
file (located at$JDG_HOME/standalone/configuration/
) to add definitions for the datasource and infinispan subsystems.- Add the following subsystem definition for the datasource:
<subsystem xmlns="urn:jboss:domain:datasources:4.0"> <!-- Define this Datasource with jndi name java:jboss/datasources/ExampleDS --> <datasources> <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true"> <!-- The connection URL uses H2 Database Engine with in-memory database called test --> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url> <!-- JDBC driver name --> <driver>h2</driver> <!-- Credentials --> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> <!-- Define the JDBC driver called 'h2' --> <drivers> <driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem>
- Add the following subsystem definition for infinispan:
<subsystem xmlns="urn:infinispan:server:core:8.0" default-cache-container="local"> <cache-container name="local" default-cache="default" statistics="true"> <local-cache name="default" start="EAGER" statistics="true"> <locking isolation="NONE" acquire-timeout="30000" concurrency-level="1000" striping="false"/> <transaction mode="NONE"/> </local-cache> <local-cache name="memcachedCache" start="EAGER" statistics="true"> <locking isolation="NONE" acquire-timeout="30000" concurrency-level="1000" striping="false"/> <transaction mode="NONE"/> </local-cache> <local-cache name="namedCache" start="EAGER" statistics="true"/> <!-- ADD a local cache called 'teams' --> <local-cache name="teams" start="EAGER" batching="false" statistics="true"> <!-- Disable transactions for this cache --> <transaction mode="NONE" /> <!-- Define the JdbcBinaryStores to point to the ExampleDS previously defined --> <string-keyed-jdbc-store datasource="java:jboss/datasources/ExampleDS" passivation="false" preload="false" purge="false"> <!-- Define the database dialect --> <property name="databaseType">H2</property> <!-- specifies information about database table/column names and data types --> <string-keyed-table prefix="JDG"> <id-column name="id" type="VARCHAR"/> <data-column name="datum" type="BINARY"/> <timestamp-column name="version" type="BIGINT"/> </string-keyed-table> </string-keyed-jdbc-store> </local-cache> <!-- End of local cache called 'teams' definition --> </cache-container> </subsystem>
Note
The Hot Rod and REST endpoints use the cache namedteams
and memcached endpoint usesmemcachedCache
as a default.Disable REST Security
As a default, thestandalone.xml
configuration file protects the REST endpoint withBASIC
authentication. This quickstart cannot perform authentication, therefore the REST authentication must be disabled in the REST connector by removing thesecurity-domain
andauth-method
parameters. The resulting configuration (with REST authentication disabled) is as follows:<rest-connector virtual-server="default-host" cache-container="local" />
For more details about security, see the REST Authentication Chapter in JBoss Data Grid's Developer Guide.Edit the Submodule Configuration File
Each submodule (specificallyhotrod-endpoint
,rest-endpoint
andmemcached-endpoint
) contains a configuration file (located at$JDG_QUICKSTART/src/main/resources/
jdg.properties
). Modify the default values in the configuration file to set the values required for your specific JBoss Data Grid installation.Navigate to the Root Directory
Open a command line and navigate to the root directory of this quickstart.Build the Application
Use the following command to build the example application in its directory:mvn clean package
This step results in the use of Maven's shade plugin, which bundles all dependencies into a single jar file for ease of use. This file is named{PROTOCOL}-endpoint-quickstart.jar
, for examplerest-endpoint-quickstart.jar
for the REST version.Start JBoss Data Grid
Run the following script to run JBoss Data Grid:$JDG_HOME/bin/standalone.sh
Run the Application
Run the example application in its directory with the following command:mvn exec:java
Chapter 17. The Rapid Stock Market Quickstart
17.1. Build and Run the Rapid Stock Market Quickstart
Procedure 17.1. Rapid Stock Market Quickstart Server-side Configuration
Navigate to the Root Directory
Open a command line and navigate to the root directory of this quickstart.- Build a server module for the JBoss Data Grid Server by packaging a class that is common for the client and server in a jar file:
$ mvn clean package -Pprepare-server-module
Place the new jar file in a directory structure that is similar to the server module. - Install the server module into the server.
- Copy the prepared module to the server:
$ cp -r target/modules ${JDG_SERVER_HOME}/
- Add the new module as a dependency of the
org.infinispan.commons
module by adding the following into themodules/system/layers/base/org/infinispan/commons/main/module.xml
file:<module name="org.infinispan.quickstart.compatibility.common"/>
- Build the application:
$ mvn clean package
- Configure the JBoss Data Grid to use the appropriate configuration file.
- Copy the example configuration file for compatibility mode to a location where the JBoss Data Grid Server can locate and use it:
$ cp ${JDG_SERVER_HOME}/docs/examples/configs/standalone-compatibility-mode.xml ${JDG_SERVER_HOME}/standalone/configuration
- Remove the
security-domain
andauth-method
attributes from therest-connector
element to disable REST security.
- Start the JBoss Data Grid Server in compatibility mode:
$ ${JDG_SERVER_HOME}/bin/standalone.sh -c standalone-compatibility-mode.xml
Procedure 17.2. Rapid Stock Market Quickstart Client-side Configuration
- In a new command line terminal window, start the client-side application:
$ mvn exec:java -Pclient
- Use the instructions in the help menu for the client application.
Chapter 18. The Cluster App Quickstart
- How to create and use a JBoss Data Grid clustered cache without having a JBoss EAP cluster.
- A configuration where the JBoss EAP cluster is independent of an Infinispan cluster.
- One JBoss EAP instance can use JBoss Data Grid caches which are members of a different JBoss Data Grid cluster.
- Programming cache configuration using the JBoss Data Grid API.
- File based configuration, seen in administration application App1Cache.
- Use CDI to inject the cache managers.
18.1. EAP Cluster App Prerequisites
- Java 8.0 (Java SDK 1.8) or better
- JBoss Enterprise Application Platform 7.0 or later
- Maven 3.0 or better
- Configure the Maven repository. For details, see Chapter 3, Install and Use the Maven Repositories.
- JBoss Data Grid modules installed in the JBoss EAP server.
18.2. Start the Application Server Instances
Procedure 18.1. Configure and Start the Servers in standalone mode
- Prepare an instance of JBoss EAP for copying:
- Unzip
jboss-datagrid-${version}-eap-modules-library.zip
. - Copy the modules to the server modules directory:
- For Linux:
cp -a jboss-datagrid-${version}-eap-modules-library/modules EAP_HOME
For Windows:xcopy /e/i/f jboss-datagrid-${version}-eap-modules-library/modules EAP_HOME\modules
- Add a user to each server for EJB access:
- For Linux: EAP_HOME/bin/add-user.sh -a -u quickuser -p quick-123
- For Windows: EAP_HOME\bin\add-user.bat -a -u quickuser -p quick-123
- Copy the prepared JBoss EAP server to 4 different directories labeled EAP_HOME[1-4].
- Open a command line for each of the 4 nodes and navigate to the root of the JBoss EAP server directory.
- Start all four of the JBoss EAP servers using the following commands:
- For Linux:
EAP_HOME1/bin/standalone.sh -Djboss.node.name=node1 EAP_HOME2/bin/standalone.sh -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 EAP_HOME3/bin/standalone.sh -Djboss.node.name=node3 -Djboss.socket.binding.port-offset=200 -c standalone-ha.xml EAP_HOME4/bin/standalone.sh -Djboss.node.name=node4 -Djboss.socket.binding.port-offset=300 -c standalone-ha.xml
- For Windows:
EAP_HOME1\bin\standalone.bat -Djboss.node.name=node1 EAP_HOME2\bin\standalone.bat -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 EAP_HOME3\bin\standalone.bat -Djboss.node.name=node3 -Djboss.socket.binding.port-offset=200 -c standalone-ha.xml EAP_HOME4\bin\standalone.bat -Djboss.node.name=node4 -Djboss.socket.binding.port-offset=300 -c standalone-ha.xml
- Add the configuration for node2 (AppOne) to use EJB server-to-server invocation:
- For Linux:
EAP_HOME2/bin/jboss-cli.sh -c --controller=localhost:10099 --file=QUICKSTART_HOME/install-appOne-standalone.cli
For Windows:EAP_HOME2\bin\jboss-cli.bat -c --controller=localhost:10099 --file=QUICKSTART_HOME/install-appOne-standalone.cli
Procedure 18.2. Configure and Start the Servers in domain mode
- Copy a fresh JBoss EAP installation to EAP_HOME:
- Unzip
jboss-datagrid-${version}-eap-modules-library.zip
. - Copy the modules to the server modules directory:
- For Linux:
cp -a jboss-datagrid-${version}-eap-modules-library/modules EAP_HOME
- For Windows:
xcopy /e/i/f jboss-datagrid-${version}-eap-modules-library/modules EAP_HOME\modules
- Open a command line and navigate to the root of JBoss EAP.
- Add a user:
- For Linux:
EAP_HOME/bin/add-user.sh -a -u quickuser -p quick-123
- For Windows:
EAP_HOME\bin\add-user.bat -a -u quickuser -p quick-123
- The following shows the command to start the domain:
- For Linux:
EAP_HOME/bin/domain.sh
- For Windows:
EAP_HOME\bin\domain.bat
- Apply the configuration for the quickstart, the domain will contain 4 nodes:
- For Linux:
EAP_HOME/bin/jboss-cli.sh -c --file=QUICKSTART_HOME/install-domain.cli
- For Windows:
EAP_HOME\bin\jboss-cli.bat -c --file=QUICKSTART_HOME/install-domain.cli
18.3. Build the Application
Procedure 18.3. Build the Application
- Open a command line and navigate to the root directory of this quickstart.
- Execute the following command to build the archive:
mvn clean install
- Copy the application to the appropriate server:
- For Linux:
cp adminApp/ear/target/jboss-eap-application-adminApp.ear EAP_HOME1/standalone/deployments cp appOne/ear/target/jboss-eap-application-AppOne.ear EAP_HOME2/standalone/deployments cp appTwo/ear/target/jboss-eap-application-AppTwo.ear EAP_HOME3/standalone/deployments cp appTwo/ear/target/jboss-eap-application-AppTwo.ear EAP_HOME4/standalone/deployments
- For Windows:
copy adminApp\ear\target\jboss-eap-application-adminApp.ear EAP_HOME1\standalone\deployments copy appOne\ear\target\jboss-eap-application-AppOne.ear EAP_HOME2\standalone\deployments copy appTwo\ear\target\jboss-eap-application-AppTwo.ear EAP_HOME3\standalone\deployments copy appTwo\ear\target\jboss-eap-application-AppTwo.ear EAP_HOME4\standalone\deployments
- When domain mode is used, deploy the applications in the following way:
- For Linux:
EAP_HOME/bin/jboss-cli.sh -c --file=QUICKSTART_HOME/deploy-domain.cli
- For Windows:
EAP_HOME\bin\jboss-cli.bat -c --file=QUICKSTART_HOME/deploy-domain.cli
18.4. Run the Application
In this example neither the AdminServer
nor the AppOneServer
are clustered at the JBoss EAP level; only the JBoss Data Grid instances are clustered as configured by the application. This application will perform the following:
- Add values to the
App1
cache, usingAdminApp
, and validated they are replicated to the server instance ofAppOne
. - Add a value to the
App2
cache, then rollback the transaction and confirm that it is not added to the cache after the rollback.
Procedure 18.4. Execute the AdminClient application
- Open a command line and navigate to the
$QUICKSTART_HOME/client/
directory. - Execute the following command:
mvn -Dexec.mainClass=org.jboss.as.quickstarts.datagrid.eap.app.AdminClient exec:java
Note
By default the application will attempt to accesslocalhost:4447
andlocalhost:4547
for theAdminHost
andAppOneHost
. This may be changed by adding the following parameter to themvn
command:-Dexec.args="AdminHost AdminPort AppOneHost AppOnePort"
- Confirm that the following text appears in the console; any unexpected results will raise an Exception:
Add a value to App1Cache with the AdminApp and check on the same instance that the value is correct added success Check the previous added value of App1Cache by accessing the AppOne Server success Add a value to App2Cache and check on the same instance that the value is correct added success Check whether changes to a cache are rollbacked if the transaction fail The cache App2 work as expected on rollback
In this example both JBoss EAP and the JBoss Data Grid caches are clustered; however, the purpose of this example is to demonstrate that the clusters are independent of one other. The JBoss Data Grid cluster is able to use a different JGroups implementation compared to the JBoss EAP servers, and this example will:
- Add values to the
App2
cache using theAdminApp
and accessAppOne
to show that the EJB invocation is clustered and bothAppTwo
instances are used.
Procedure 18.5. Execute the AppOneClient
- Open a command line and navigate to the
$QUICKSTART_HOME/client/
directory. - Execute the following command:
mvn -Dexec.mainClass=org.jboss.as.quickstarts.datagrid.eap.app.AppOneClient exec:java
- Confirm that the following text appears in the console; any unexpected results will raise an Exception:
Add a value to App2Cache with the AdminApp Access the App2Cache from the AppOneServer by using the clustered EJB@AppTwoServer success : received the following node names for EJB invocation : [node3, node4]
18.5. Debug the Application
mvn dependency:sources mvn dependency:resolve -Dclassifier=javadoc
Chapter 19. The camel-jbossdatagrid-fuse Quickstart
local_cache_producer
and local_cache_consumer
, on Fuse, one on each container child1
and child2
respectivity. Below is a description of each of the bundles:
local_cache_producer
: Scans a folder (/tmp/incoming) for incoming CSV files of the format "id, firstName, lastName, age". If a file is dropped with entries in the given format, each entry is read and transformed into a Person POJO and stored in the data grid.local_cache_consumer
: Lets you query for a POJO using a RESTful interface and receive a JSON representation of the Person POJO stored in the data grid for the given key
infinispan.xml
and jgroups.xml
files. The infinispan.xml
file defines a REPL
(replicated) cache named camel-cache
, and both the consumer and producer interact with this cache.
19.1. Quickstart Prerequisites
- Java 7.0 (Java SDK 1.7) or better
- Maven 3.0 or better
- JBoss Fuse 6.2.0 or better
- Configure the Maven Repository. For details, see Chapter 3, Install and Use the Maven Repositories
19.2. Setup
- Download the Fuse Full Install binary from the Red Hat Customer Portal.
- Export the path to the folder where the CSV files will be placed by running the command:
export incomingFolderPath=[Full path to the CSV folder]
- Run the following command in the root directory of the quickstart:
mvn clean install -DincomingFolderPath=$incomingFolderPath
- Set the
FUSE_INSTALL_PATH
andFUSE_BINARY_PATH
variables in the same shell:export FUSE_INSTALL_PATH = [Full path to the folder where Fuse will be installed] export FUSE_BINARY_PATH = [Full path to the Fuse zip file downloaded in step 1]
- If running the camel-jbossdatagrid-fuse quickstart in JBoss Fuse 6.2.1 the following changes to the
setupEverythingOnFuse.sh
script must be made; otherwise proceed to the next step:- Change the version of Fuse being exported to reference the 6.2.1 component.
- Update the container name to
child1
.
# Original line with old version # export FUSE_VERSION=jboss-fuse-6.2.0.redhat-133 # Updated line for Fuse 6.2.1: export FUSE_VERSION=jboss-fuse-6.2.1.redhat-084 [...] # Original line exporting the profile #sh client -r 2 -d 10 "fabric:container-add-profile child demo-local_producer" > /dev/null 2>&1 # Updated line for Fuse 6.2.1: sh client -r 2 -d 10 "fabric:container-add-profile child1 demo-local_producer" > /dev/null 2>&1
- Once the environment variables are set run the following from the root directory of the quickstart:
./setupEverythingOnFuse.sh
- After the script completes confirm that the Fuse Hawtio Console may be accessed without error. This console, by default, runs at
http://127.0.0.1:8181/hawtio/index.html#/login
; the username and password are bothadmin
. - Confirm that both the
child1
andchild2
containers were created by accessing Fuse Fabric athttp://127.0.0.1:8181/hawtio/index.html#/fabric/containers
. Both containers should be highlighted in green to indicate they are ready.
19.3. Testing the camel-jbossdatagrid-fuse Quickstart
local_cache_producer
create a CSV file in the incomingFolderPath
, previously specified. The following command will generate a file with a single entry:
echo "1,Bill,Gates,59" > $incomingFolderPath/sample.csvOnce the file has been removed from the directory then the producer has successfully parsed the file. Proceed to testing the consumer.
local_cache_consumer
navigate to http://127.0.0.1:8282/cache/get/1
in a web browser. This will query the cache for the entry with an Id of 1
, which was specified above. The following JSON of the created POJO should be returned:
{"id":1,"firstName":"Bill","lastName":"Gates","age":59}
Part VII. Uninstall Red Hat JBoss Data Grid
Chapter 20. Remove Red Hat JBoss Data Grid
20.1. Remove Red Hat JBoss Data Grid from Your Linux System
Warning
Procedure 20.1. Remove JBoss Data Grid from Your Linux System
Shut Down Server
Ensure that the JBoss Data Grid server is shut down.Navigate to the JBoss Data Grid Home Directory
Use the command line to change into the level above the$JDG_HOME
folder.Delete the JBoss Data Grid Home Directory
Enter the following command in the terminal to remove JBoss Data Grid, replacing$JDG_HOME
with the name of your JBoss Data Grid home directory:$ rm -Rf $JDG_HOME
20.2. Remove Red Hat JBoss Data Grid from Your Windows System
Warning
Procedure 20.2. Remove JBoss Data Grid from Your Windows System
Shut Down Server
Ensure that the JBoss Data Grid server is shut down.Navigate to the JBoss Data Grid Home Directory
Use the Windows Explorer to navigate to the directory in which the$JDG_HOME
folder is located.Delete the JBoss Data Grid Home Directory
Select the$JDG_HOME
folder and delete it.
Appendix A. References
A.1. About Key-Value Pairs
- A key is unique to a particular data entry. It consists of entry data attributes from the related entry.
- A value is the data assigned to and identified by the key.
Appendix B. Maven Configuration Information
B.1. Install the JBoss Enterprise Application Platform Repository Using Nexus
Procedure B.1. Download the JBoss Enterprise Application Platform 6 Maven Repository ZIP archive
- Open a web browser and access the following URL: https://access.redhat.com/jbossnetwork/restricted/listSoftware.html?product=appplatform.
- Find Application Platform 6 Maven Repository in the list.
- Clickto download a ZIP file that contains the repository.
- Unzip the files into the desired target directory.
Procedure B.2. Add the JBoss Enterprise Application Platform 6 Maven Repository using Nexus Maven Repository Manager
- Log into Nexus as an Administrator.
- Select the Repositories section from the → menu to the left of your repository manager.
- Click the Add... drop-down menu, then select Hosted Repository.
- Provide a name and ID for the new repository.
- Enter the unzipped repository path in the Override Local Storage Location field.
- Continue if the artifact must be available in a repository group. If not, do not continue with this procedure.
- Select the repository group.
- Click on the Configure tab.
- Drag the new JBoss Maven repository from the Available Repositories list to the Ordered Group Repositories list on the left.
Note
The order of this list determines the priority for searching Maven artifacts.
The repository is configured using Nexus Maven Repository Manager.
B.2. Maven Repository Configuration Example
example-settings.xml
is available in the root directory of the Maven repository folder after it is unzipped. The following is an excerpt that contains the relevant parts of the example-settings.xml
file:
Example B.1. Sample Maven Repository Configuration
<?xml version="1.0" encoding="UTF-8"?> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>jboss-datagrid-repository</id> <repositories> <repository> <id>jboss-datagrid-repository</id> <name>JBoss Data Grid Maven Repository</name> <url>JDG_REPOSITORY_URL</url> <layout>default</layout> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>false</enabled> <updatePolicy>never</updatePolicy> </snapshots> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>jboss-datagrid-repository</id> <name>JBoss Data Grid Maven Repository</name> <url>JDG_REPOSITORY_URL</url> <layout>default</layout> <releases> <enabled>true</enabled> <updatePolicy>never</updatePolicy> </releases> <snapshots> <enabled>false</enabled> <updatePolicy>never</updatePolicy> </snapshots> </pluginRepository> </pluginRepositories> </profile> </profiles> <activeProfiles> <!-- make the profile active by default --> <activeProfile>jboss-datagrid-repository</activeProfile> </activeProfiles> </settings>
JDG_REPOSITORY_URL
may be found by following the instructions in Section B.3, “Determining the URL of the JBoss Data Grid Repository”.
B.3. Determining the URL of the JBoss Data Grid Repository
- To use the online JBoss Data Grid Maven repository, specify the following URL: https://maven.repository.redhat.com/ga/
- To use a JBoss Data Grid Maven repository installed on the local file system, you must download the repository and then use the local file path for the URL. For example:
file:///path/to/repo/jboss-datagrid-7.0.0-maven-repository/maven-repository/
- If you install the JBoss Data Grid Maven repository using the Nexus Repository Manager, the URL will look something like the following: https://intranet.acme.com/nexus/content/repositories/jboss-datagrid-7.0.0-maven-repository/maven-repository/
Appendix C. Revision History
Revision History | ||||
---|---|---|---|---|
Revision 7.0.0-4 | Wed 9 Nov 2016 | |||
| ||||
Revision 7.0.0-3 | Fri 22 Jul 2016 | |||
| ||||
Revision 7.0.0-2 | Mon 18 Jul 2016 | |||
| ||||
Revision 7.0.0-0 | Tue 19 Apr 2016 | |||
|