Configuration - ModeShape 4

There are three ways to configure ModeShape, and it depends on how you're deploying your application.

ModeShape and JBoss Wildfly - When ModeShape is installed into JBoss Wildfly, it is configured using the Wildfly configuration and tools (e.g., the command line interface, or CLI). For more details, see Configuring ModeShape in Wildfly.
ModeShape via JCA - When your application is to be deployed to an environment that supports the Java Connector Architecture (JCA), then you can deploy ModeShape repositories via ModeShape's JCA adapter (available in ModeShape 3.1 or later). See ModeShape's JCA Adapter for more details.
Embedded ModeShape - In all other cases, ModeShape runs within your application, whether your application is a regular Java SE application or a web application deployed to a web container. This means that your application needs to create a single ModeShape engine, deploy a JSON configuration file for each of the repositories needed by your application, and shut down the engine when your application is shut down. See ModeShape in Java applications for more details.

Infinispan Configuration

In all cases, you still need to configure Infinispan. There are a few things to keep in mind:

Minimally, the cache used by a repository needs to be transactional, since ModeShape internally uses transactions and works with client-initiated or container-managed JTA transactions.

Applications that may be concurrently updating the same nodes should use Infinispan configured to use pessimistic locking with the READ_COMMITTED isolation level. By default Infinispan will use optimistic locking; this is more efficient for applications that don't update the same nodes, but concurrently updating the same nodes with optimistic locking may very well cause some updates to be lost. If you're not sure, use pessimistic locking.

Embedded

The following are some sample Infinispan configuration snippets using a SingleFileStore:

Infinispan 6

<?xml version="1.0" encoding="UTF-8"?>
<infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:infinispan:config:6.0 http://www.infinispan.org/schemas/infinispan-config-6.0.xsd"
            xmlns="urn:infinispan:config:6.0">

    <global>
        <globalJmxStatistics enabled="false" allowDuplicateDomains="true"/>
    </global>

    <namedCache name="persistentRepository">
        <eviction strategy="LIRS" maxEntries="1000"/>
        <transaction
                transactionManagerLookupClass="org.infinispan.transaction.lookup.GenericTransactionManagerLookup"
                transactionMode="TRANSACTIONAL"
                lockingMode="PESSIMISTIC"/>
        <persistence
                passivation="false">
            <singleFile
                    shared="false"
                    preload="false"
                    fetchPersistentState="false"
                    purgeOnStartup="false"
                    location="target/persistent_repository/store">
            </singleFile>
        </persistence>
    </namedCache>
</infinispan>

Infinispan 7

<?xml version="1.0" encoding="UTF-8"?>
<infinispan xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="urn:infinispan:config:7.2 http://www.infinispan.org/schemas/infinispan-config-7.2.xsd"
            xmlns="urn:infinispan:config:7.2">
    
    <cache-container default-cache="persistentRepository" statistics="false">
        <jmx duplicate-domains="true"/>
        <local-cache name="persistentRepository" statistics="false">
            <transaction
                    mode="NON_XA"
                    locking="PESSIMISTIC"/>
            <persistence 
                    passivation="false">
                <file-store fetch-state="false"
                            shared="false"
                            preload="false"
                            purge="false"
                            path="target/persistent_repository/store"/>
            </persistence>
        </local-cache>
    </cache-container>
</infinispan>

EAP/Wildfly

Starting with 4.3.0.Final, ModeShape no longer uses the Infinispan Wildfly subsystem

Wildfly will use REPEATABLE_READ as the default isolation level. If an application is concurrently changing the same node, it must make sure to change this default to READ_COMMITTED

Infinispan EAP/Wildfly Pessimistic Locking

<local-cache name="sample">
   <locking isolationLevel="READ_COMMITTED"/>
   <!-- ModeShape requires transactions -->
   <transaction mode="NON_XA" locking="PESSIMISTIC"/>
   <!-- Without eviction all entries are held in memory and never released -->
   <eviction strategy="LRU" max-entries="10000"/>
   <!-- Use a cache with file-backed write-through storage. File-backed storage is simple, but not necessarily the fastest. -->
   <file-store passivation="false" path="modeshape/store/sample" relative-to="jboss.server.data.dir" purge="false"/>
</local-cache>

Transactions

When working with transactions, Infinispan can be configured to behave differently with regards to the cache interaction with the TransactionManager. There are essentially 2 major approaches: making the cache & cache store enroll & participate as a Synchronization or as a full XAResource. Depending on which you choose, you may get different behaviors as far as the atomicity of the ModeShape/Infinispan cache/Infinispan cache store sequence of operations.

For example, when using Synchronizations with the JBOSS Transaction Manager, transaction failures that happen on commit may not propagate back to ModeShape (see https://issues.jboss.org/browse/MODE-2427 and https://developer.jboss.org/message/918679 for a more detailed discussion on this topic)

When configuring Infinispan in embedded mode, the following attributes are available:

Infinispan 6 Advanced Transactional Configuration

 <!--
   By default: useSynchronization=true, syncCommitPhase=true and syncRollbackPhase=false
 -->
 <transaction
   transactionManagerLookupClass="org.infinispan.transaction.lookup.GenericTransactionManagerLookup"
   transactionMode="TRANSACTIONAL"
   lockingMode="PESSIMISTIC"
   useSynchronization="true"
   syncCommitPhase="true"
   syncRollbackPhase="true"
 >
   <!-- Disabled by default -->
   <recovery enabled="true"/>
</transaction>

In Infinispan 7, the above configuration switches can be controlled via the transaction mode attribute, with the following possible values:

Infinispan 7 Transaction Modes

  <xs:simpleType name="transaction-mode">
    <xs:restriction base="xs:token">
      <xs:enumeration value="NONE">
        <xs:annotation>
          <xs:documentation>Cache will not enlist within transactions.</xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="BATCH">
        <xs:annotation>
          <xs:documentation>Uses batching to group cache operations together.</xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="NON_XA">
        <xs:annotation>
          <xs:documentation>Cache will enlist within transactions as a javax.transaction.Synchronization</xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="NON_DURABLE_XA">
        <xs:annotation>
          <xs:documentation>Cache will enlist within transactions as a javax.transaction.xa.XAResource, without recovery.</xs:documentation>
        </xs:annotation>
      </xs:enumeration>
      <xs:enumeration value="FULL_XA">
        <xs:annotation>
          <xs:documentation>Cache will enlist within transactions as a javax.transaction.xa.XAResource, with recovery.</xs:documentation>
        </xs:annotation>
      </xs:enumeration>
    </xs:restriction>
  </xs:simpleType>

So the previous configuration would be written as:

Infinispan 7 Advanced Transactional Configuration

<transaction
   mode="FULL_XA"
   locking="PESSIMISTIC"/>

The Wildfly equivalent of those configuration switches is controlled via the transaction mode attribute value, as follows:

Mode	Description
NON_XA	useSynchronization=true && recovery.enabled=false
NON_DURABLE_XA	useSynchronization=false && recovery.enabled=false && syncCommitPhase=true && syncRollbackPhase=true
FULL_XA	useSynchronization=false && recovery.enabled=true && syncCommitPhase=true && syncRollbackPhase=true

For a more detailed explanation of the semantics of each attribute, read the Infinispan documentation.

Clustering

Starting with 4.0.0.Final, ModeShape uses the same JGroups configuration as Infinispan, without requiring a separate configuration to be maintained. However, for ModeShape to work correctly in a cluster it is important that the JGroups stack is configured to dispatch local changes in the same thread. This is accomplished via 2 JGroups configuration attributes:

JGroups Attributes

 <PROTOCOL>
    ....
    thread_pool.enabled="false"
    oob_thread_pool.enabled="false"
 </PROTOCOL>