Chapter 4. Using JBoss Data Grid with Supported Containers

4.1. Using JBoss Data Grid with Supported Containers

Red Hat JBoss Data Grid can be used in the following runtimes:

  • 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.

For a list of containers supported with Red Hat JBoss Data Grid, see the Release Notes or the support information here: https://access.redhat.com/articles/2435931

4.2. Deploy JBoss Data Grid in JBoss EAP (Library Mode)

Red Hat JBoss Data Grid provides a set of modules for Red Hat JBoss Enterprise Application Platform 7.x. Using these modules means that JBoss Data Grid libraries do not need to be included in the user deployment. To avoid conflicts with the Infinispan modules that are already included with JBoss EAP, the JBoss Data Grid modules are placed within a separate slot and identified by the JBoss Data Grid version (major.minor).

Note

The JBoss EAP modules are not included in JBoss EAP. Instead, navigate to the Customer Support Portal at http://access.redhat.com to download these modules from the Red Hat JBoss Data Grid downloads page.

To deploy JBoss Data Grid in JBoss EAP, add dependencies from the JBoss Data Grid module to the application’s classpath (the JBoss EAP deployer) in one of the following ways:

  • 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 a Dependency to the jboss-deployment-structure.xml 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" slot="jdg-7.2" services="export"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>
Note

For details about the jboss-deployment-structure.xml file, see the Red Hat JBoss Enterprise Application Platform documentation.

Add a Dependency to the MANIFEST.MF File.

Add a dependency to the MANIFEST.MF files as follows:

MANIFEST.MF File

Manifest-Version: 1.0
Dependencies: org.infinispan:jdg-7.2 services

The first line remains the same as the example. Depending on the dependency required, add one of the following to the second line of the file:

  • JBoss Data Grid Core: 

    Dependencies: org.infinispan:jdg-7.2 services

  • Embedded Query: 

    Dependencies: org.infinispan:jdg-7.2 services, org.infinispan.query:jdg-7.2 services, org.infinispan.query.dsl:jdg-7.2 services

  • JDBC Cache Store: 

    Dependencies: org.infinispan:jdg-7.2 services, org.infinispan.persistence.jdbc:jdg-7.2 services

  • JPA Cache Store: 

    Dependencies: org.infinispan:jdg-7.2 services, org.infinispan.persistence.jpa:jdg-7.2 services

  • LevelDB Cache Store: 

    Dependencies: org.infinispan:jdg-7.2 services, org.infinispan.persistence.leveldb:jdg-7.2 services

  • CDI: 

    Dependencies: org.infinispan:jdg-7.2 services, org.infinispan.cdi:jdg-7.2 meta-inf

Generate the MANIFEST.MF file via Maven

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.2 services</Dependencies>
			</manifestEntries>
		</archive>
	</configuration>
</plugin>

4.3. Deploy JBoss Data Grid in JBoss EAP (Remote Client-Server Mode)

4.3.1. Deploy JBoss Data Grid in JBoss EAP (Remote Client-Server Mode)

Red Hat JBoss Data Grid provides a set of modules for Red Hat JBoss Enterprise Application Platform 7.x. Using these modules means that JBoss Data Grid libraries do not need to be included in the user deployment. To avoid conflicts with the Infinispan modules that are already included with JBoss EAP, the JBoss Data Grid modules are placed within a separate slot and identified by the JBoss Data Grid version (major.minor).

Note

The JBoss EAP modules are not included in JBoss EAP. Instead, navigate to the Customer Support Portal at http://access.redhat.com to download these modules from the Red Hat JBoss Data Grid downloads page.

To deploy JBoss Data grid in JBoss EAP, add dependencies from the JBoss Data Grid module to the application’s classpath (the JBoss EAP deployer) in one of the following ways:

  • Add a dependency to the jboss-deployment-structure.xml file.
  • Add a dependency to the MANIFEST.MF file.

Add a Dependency to the jboss-deployment-structure.xml 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.2" services="export"/>
            <module name="org.infinispan.client.hotrod" slot="jdg-7.2" services="export"/>
        </dependencies>
    </deployment>
</jboss-deployment-structure>
Note

For details about the jboss-deployment-structure.xml file, see the Red Hat JBoss Enterprise Application Platform documentation.

Add a Dependency to the MANIFEST.MF File.

Add a dependency to the MANIFEST.MF files as follows:

Example MANIFEST.MF File

Manifest-Version: 1.0
Dependencies: org.infinispan.commons:jdg-7.2 services, org.infinispan.client.hotrod:jdg-7.2 services

The first line remains the same as the example. Depending on the dependency required, add one of the following to the second line of the file:

  • Basic Hot Rod client: 

    org.infinispan.commons:jdg-7.2 services, org.infinispan.client.hotrod:jdg-7.2 services

  • Hot Rod client with Remote Query functionality: 

    org.infinispan.commons:jdg-7.2 services, org.infinispan.client.hotrod:jdg-7.2 services, org.infinispan.query.dsl:jdg-7.2 services, org.jboss.remoting3

4.3.2. Using Custom Classes with the Hot Rod client

Either of the following two methods may be used to use 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:

    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 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-7.x/module.xml .

4.4. Deploy JBoss Data Grid in JBoss Enterprise Web Server

Red Hat JBoss Data Grid supports JBoss Enterprise Web Server in Library and Remote Client Server mode. To use JBoss Data Grid with JBoss Enterprise Web Server, bundle the JDG libraries in a web application and deploy the application on the server.

For further information on how to deploy JBoss Data Grid on JBoss Enterprise Web Server, see the Carmart Non-Transactional Quickstart in Red Hat JBoss Data Grid Quickstarts.

4.5. Deploy Web Applications on WebLogic Server (Library Mode)

Red Hat JBoss Data Grid supports the WebLogic 12c application server in Library mode. The following procedure describes how to deploy web applications on a WebLogic server.

Prerequisites

The prerequisites to deploy the web applications are as follows:

  1. WebLogic Server 12c.
  2. JBoss Data Grid Library (Embedded) mode.

Deploying Web Applications on a WebLogic Server

  1. Create Web Applications

    Create a web application and add the libraries in the WEB-INF folder.

  2. Create a weblogic.xml Deployment Descriptor

    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

    The prefer-web-inf-classes class indicates that the libraries and the classes in the WEB-INF/lib folder is preferred over the default libraries bundled in the WebLogic server. For example, the commons-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.

  3. 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 the WEB-INF folder along with the WebLogic deployment descriptor file.

  4. Deploy the Application onto the 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 file p17424706_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.6. Deploy Web Applications on WebLogic Server (Remote Client-Server Mode)

Red Hat JBoss Data Grid supports the WebLogic 12c application server in Remote Client-Server mode. The following procedure describes how to deploy web applications on a WebLogic server.

Deploying Web Applications on a WebLogic Server

  1. To install the WebLogic server, see http://docs.oracle.com/cd/E24329_01/doc.1211/e24492/toc.htm.
  2. 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 Run Red Hat JBoss Data Grid in Remote Client-Server Mode.
  3. Create a web application and add the infinispan-remote library as a dependency if Maven is used.

  4. 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

    The prefer-web-inf-classes class indicates that the libraries and classes in the WEB-INF/lib folder are preferred over the default libraries bundled in the WebLogic server. For example, the commons-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.

  5. Add deployment descriptor file in the WEB-INF folder.

  6. Ensure that the infinispan-remote dependency is added to the pom.xml file, then use a Maven plugin to create a web archive.

    Alternatively, create the web archive manually and add the library manually.

  7. 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.7. Running Red Hat JBoss Data Grid in Karaf (OSGi)

4.7.1. Running Red Hat JBoss Data Grid in Karaf (OSGi)

Apache Karaf is a powerful, lightweight OSGi-based runtime container into which components and applications are deployed. OSGi implements a dynamic component model that does not exist in standalone JVM environments. OSGi containers such as Karaf include a rich set of tools for managing the life cycle of an application.

All dependencies between individual modules, including version numbers, must be explicitly specified. Where more than one class of the same name exists, the strict rules of OSGi specify which of the classes will be used by your bundle.

4.7.2. Running a Deployment of JBoss Data Grid in Karaf (Remote Client-Server)

The Red Hat JBoss Data Grid Hot Rod client can be run in an OSGi-based container such as Karaf, allowing client applications deployed in Karaf to connect to pre-existing JBoss Data Grid servers.

Use the path in the JBoss Data Grid Maven repository to set up Karaf. Additionally, JBoss Data Grid requires a 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.7.3. Installing the Hot Rod client feature in Karaf

Red Hat JBoss Data Grid’s Hot Rod feature is installed in Karaf as follows:

Prerequisite

Configure the Red Hat JBoss Data Grid Maven Repository.

Install the Hot Rod Feature in Karaf

  1. 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

  2. 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.7.4. Installing Red Hat JBoss Data Grid in Karaf (Library Mode)

The Red Hat JBoss Data Grid JAR files contain the required OSGi manifest headers and are used inside OSGi runtime environments as OSGi bundles. Additionally, the required third-party dependencies must be installed. These can be installed individually, or altogether via the features file, which defines all required dependencies.

To install bundles using the features file:

  • Register the feature repositories inside Karaf.
  • Install the features contained in the repositories.

Installing bundles using the features file

  1. Start the Karaf console

    Start the Karaf console using the following commands: 

    $ cd $APACHE_KARAF_HOME/bin
$ ./karaf

  2. Register a feature repository

    Register a feature repository as follows:

    1. For Karaf 2.3.3: 

      karaf@root() features:addUrl mvn:org.infinispan/infinispan-embedded/${VERSION}/xml/features
      karaf@root features:install infinispan-embedded

    2. For Karaf 3.0.0: 

      karaf@root() feature:repo-add mvn:org.infinispan/infinispan-embedded/${VERSION}/xml/features
      karaf@root feature:install infinispan-embedded

The URL for feature repositories is constructed from the Maven artifact coordinates using the following format: 

mvn:<groupId>/<artifactId>/<version>/xml/features
Important

The JPA Cache Store is not supported in Apache Karaf in JBoss Data Grid 7.2.

Important

Querying in Library mode (which is covered in the JBoss Data Grid Developer Guide ) is not supported in Apache Karaf in JBoss Data Grid 7.2.