Getting Started Guide

Procedure 2.1. Install OpenJDK on Red Hat Enterprise Linux

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

2. Install the Package

   Use the yum utility to install OpenJDK:

   $ sudo yum install java-1.6.0-openjdk-devel
   

3. Verify that OpenJDK is the System Default

   Ensure that the correct JDK is set as the system default as follows:
   1. Log in as root and run the alternatives command:

      $ /usr/sbin/alternatives --config java

   2. Depending on the OpenJDK version, select /usr/lib/jvm/jre-1.6.0-openjdk.x86_64/bin/java /usr/lib/jvm/jre-1.7.0-openjdk.x86_64/bin/java.
   3. Use the following command to set javac:

      $ /usr/sbin/alternatives --config javac

   4. Depending on the OpenJDK version used, select /usr/lib/jvm/java-1.6.0-openjdk/bin/java or /usr/lib/jvm/java-1.7.0-openjdk/bin/java.

Procedure 3.1. Download JBoss Data Grid

1. Access the Customer Service Portal

   Log into the Customer Service Portal at https://access.redhat.com.

2. Locate the Product

   Mouse over Downloads and navigate to JBoss Enterprise Middleware.

3. Select the Product

   Select Data Grid.

4. Download JBoss Data Grid

   Select the appropriate JBoss Data Grid download and click the Download link.
   Select JBoss Data Grid Server {VERSION} for JBoss Data Grid with the Remote Client-Server usage mode or JBoss Data Grid Library {VERSION} for JBoss Data Grid with the Library usage mode.

Procedure 3.2. Verify the Downloaded File

1. To verify that a file downloaded from the Red Hat Customer Portal is error-free, whilst still on the portal site, go to that package's Software Details page. Here you will find MD5 and SHA256"checksum" values that you will use to check the integrity of the file.
2. Open a terminal window and run either either the md5sum or sha256sum command, supplying the filename of the downloaded ZIP as an argument. The program will output the checksum value for the file.
3. 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. Users of that operating system will have to download a third-party product instead.

Procedure 3.3. Install JBoss Data Grid

1. Copy the downloaded JBoss Data Grid package to the preferred location on your machine.
2. Run the following command to unzip 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.
3. The resulting unzipped directory will now be referred to as $JDG_HOME.

Procedure 7.1. Create a Main Method in the Quickstart Class

1. Create the Quickstart.java File

   Create a file called Quickstart.java at your project's location.

2. Add the Quickstart Class

   Add the following class and method:

   import org.infinispan.manager.DefaultCacheManager
   import org.infinispan.Cache
   
   package com.mycompany.app;
   public class Quickstart {
     public static void main(String args[]) throws Exception {
          Cache<Object, Object> c = new DefaultCacheManager().getCache();
       }
    }
   

3. Copy Dependencies and Compile Java Classes

   Use the following command to copy all project dependencies to a directory and compile the java classes from our project:

   $ mvn clean compile dependency:copy-dependencies -DstripVersion
   

4. Run the Main Method

   Use the following command to run the main method:

   $ java -cp target/classes/:target/dependency/* com.mycompany.app.Quickstart
   

Procedure 9.1. Find the JBoss Data Grid Sample Configuration for a Node Without Endpoints

1. Extract the JBoss Data Grid ZIP

   1. Extract the ZIP file for JBoss Data Grid Remote Client-Server mode. This is named jboss-datagrid-server-${version}-GA. Add the relevant version to the file name.

2. Navigate to the Appropriate Folder

   In the extracted folder, navigate to the $JDG_HOME/docs/examples/config folder.

3. Find the Configuration Sample File

   View the standalone-storage-only.xml file, which contains the configuration for a node with no endpoints.

Procedure 10.1. Monitor JBoss Data Grid Applications in JBoss Enterprise Application Platform

1. Configure RHQ/JBoss Operations Network

   Add an RHQ/JBoss Operations Network specific property (named org.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.

2. 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's tools.jar file.
   To configure your RHQ/JBoss Operations Network agent to use the JDK, follow the instructions relevant to your operating system:
   1. For Linux users, set the RHQ_AGENT_JAVA_HOME environment variable to the JDK home directory in the agent's rhq-agent-env.sh file.
   2. For Windows users, set the RHQ_AGENT_JAVA_HOME environment variable to the JDK home directory in the agent's rhq-agent-env.bat file.

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

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

Procedure 11.1. Start the First Application Server Instance

1. Navigate to the Root Directory

   In the command line terminal, navigate to the root for your JBoss server directory.

2. 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:
   1. For Linux:

      $JBOSS_HOME/bin/standalone.sh

   2. For Windows:

      $JBOSS_HOME\bin\standalone.bat

Procedure 11.2. Start the Second Application Server Instance

1. Clone the Application Server

   Create a copy of the selected JBoss Server to create a second instance.

2. Navigate to the Root Directory

   In the command line terminal, navigate to the root for your JBoss server directory.

3. 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.
   1. For Linux:

      $JBOSS_HOME2/bin/standalone.sh -Djboss.socket.binding.port-offset=100

   2. For Windows:

      $JBOSS_HOME2\bin\standalone.bat -Djboss.socket.binding.port-offset=100

Procedure 11.3. Build and Deploy the Hello World Quickstart

1. Navigate to the Required Directory

   In the command line terminal, navigate to the root directory of the quickstart on the command line interface.

2. 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 jboss-as:deploy

   This command deploys target/jboss-as-helloworld-jdg.war to the first running server instance.

3. 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 jboss-as:deploy -Djboss-as.port=10099

   This command deploys target/jboss-as-helloworld-jdg.war to the second running server instance.

Procedure 11.4. Test Replication on the Application

1. Access the First Server

   Access the first application server and enter the key and value.
   1. Access the first application server in a browser window using the following URL:

      http://localhost:8080/jboss-as-helloworld-jdg

   2. Insert the key foo.
   3. Insert the value bar.

2. Access the Second Server

   Access the second application server and enter the key and value.
   1. Access the second application server in a browser window using the following URL:

      http://localhost:8180/jboss-as-helloworld-jdg

   2. Click Get Some.
   3. Get the key foo.
   4. Click Put Some More.
   5. Insert the key mykey.
   6. Insert the value myvalue.

3. Get All Keys and Values

   Access the first server and request all keys.
   1. Access the first application server in a browser window using the following URL:

      http://localhost:8080/jboss-as-helloworld-jdg

   2. Click Get Some.
   3. Click Get All to request all key and values.

Procedure 11.5. Remove the Application

1. Start the Application Servers

   Ensure that both server instances are running.

2. Navigate to the Root

   In the command line terminal, navigate to the root directory of the quickstart

3. Remove the Archive

   Use the following commands to remove the archive from both the server instances.
   1. Remove the archive from the first server as follows:

      mvn jboss-as:undeploy

   2. Remove the archive from the second server as follows:

      mvn jboss-as:undeploy -Ddeploy.port=10099

Procedure 13.1. Build the Football Application

1. Add Configurations

   Edit the standalone.xml file (located at $JDG_HOME/standalone/configuration/) to add definitions for the datasource and infinispan subsystems.
   1. Add the following subsystem definition for the datasource:

      
      <subsystem xmlns="urn:jboss:domain:datasources:1.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>
      
      

   2. Add the following subsystem definition for infinispan:

      
      <subsystem xmlns="urn:infinispan:server:core:5.2"
      	     default-cache-container="local">
      
      	<cache-container name="local" 
      			 default-cache="default">
      
      	        <local-cache name="default" 
      			     start="EAGER">
      
      			<locking isolation="NONE" 
      				 acquire-timeout="30000" 
      				 concurrency-level="1000" 
      				 striping="false"/>
      
      			<transaction mode="NONE"/>
      
      		</local-cache>
      
      		<local-cache name="memcachedCache" 
      			     start="EAGER">
      
      			<locking isolation="NONE" 
      				 acquire-timeout="30000" 
      				 concurrency-level="1000" 
      				 striping="false"/>
      			<transaction mode="NONE"/>
      
      		</local-cache>
      
      	        <local-cache name="namedCache" 
      			     start="EAGER" />
      	
      	        <!-- ADD a local cache called 'teams' -->
      	
      		<local-cache name="teams"
      		             start="EAGER"
      	         	     batching="false"
      		             indexing="NONE" >
      	
      	            <!-- Define the locking 
      			isolation of this cache -->
      
      			<locking isolation="REPEATABLE_READ"
      	                	 acquire-timeout="20000"
      	                	 concurrency-level="500"
      		                 striping="false" />
      
      	            <!-- Disable transactions for this cache -->
      			<transaction mode="NONE" />
      
      	            <!-- Define the JdbcBinaryCacheStores 
      			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 named teams and memcached endpoint uses memcachedCache as a default.

2. Disable REST Security

   As a default, the standalone.xml configuration file protects the REST endpoint with BASIC authentication. This quickstart cannot perform authentication, therefore the REST authentication must be disabled in the REST connector by removing the security-domain and auth-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, refer to the REST Authentication Chapter in JBoss Data Grid's Developer Guide.

3. Edit the Submodule Configuration File

   Each submodule (specifically hotrod-endpoint, rest-endpoint and memcached-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.

4. 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 example rest-endpoint-quickstart.jar for the REST version.

5. Start JBoss Data Grid

   Run the following script to run JBoss Data Grid:

   $JDG_HOME/bin/standalone.sh
   

6. Run the Application

   Run the example application in its directory with the following command:

   mvn exec:java
   

Procedure 14.1. Remove JBoss Data Grid from Your Linux System

1. Shut Down Server

   Ensure that the JBoss Data Grid server is shut down.

2. Navigate to the JBoss Data Grid Home Directory

   Use the command line to change into the level above the $JDG_HOME folder.

3. 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 name of your JBoss Data Grid home directory:

   $ rm -Rf $JDG_HOME
   

Procedure 14.2. Remove JBoss Data Grid from Your Windows System

1. Shut Down Server

   Ensure that the JBoss Data Grid server is shut down.

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

3. Delete the JBoss Data Grid Home Directory

   Select the $JDG_HOME folder and delete it.