HA-JNDI Implementation

Overview

The JBoss AS Clustering Guide contains an HA-JNDI chapter,  describing how to configure and use HA-JNDI.  This document supplements the material presented there and also describes internal changes made to HA-JNDI in JBoss AS 5.0.

HA-JNDI is a feature that assists with failover and load-balancing capabilities in a cluster.  It provides a cluster-global context so that serializable objects can be bound and made available on all nodes in the cluster.  Objects bound through HA-JNDI are replicated throughout the cluster and accessible via HA-JNDI lookup.  HA-JNDI also provides for cluster-wide lookups of objects bound using standard JNDI so that an object bound in local JNDI (e.g., port 1099) and located on a single node in a cluster can be accessed from any node via HA-JNDI.

AS 6.0 Implementation

In JBoss AS 6.0, the HA-JNDI has been integrated with Infinispan which replaced JBossCache as the way that we share information between cluster nodes (with JGroups providing the underlying group communications layer and much more...). 

AS 5.x Implementation

In JBoss AS 5.x, HA-JNDI is  based upon the JBossCache implementation.  Each HA-JNDI node has its own instance of JBossCache which is used to store bindings and perform lookups.  Replication is handled transparently by the cache.  Lookups accessing local JNDI NamingServer instances are explicitly propagated via JBossCache RPC calls.

HA-JNDI 5.x Binding Process

Each HA-JNDI node stores its bindings in a TreeCache instance.  All HA-JNDI bindings are located under a root FQN of

__HA_JNDI__

so that the cache can be shared with other modules.  Each JNDI context is stored in the cache as a node; each binding associated with the context is stored as a key/value pair in the node's hashmap.  The cache instance is configured for replication so that the bindings are automatically propagated throughout the cluster.

HA-JNDI 5.x Lookup Process

HA-JNDI lookups utilize the following sequence, terminating as soon as the lookup is successful.

1. Retrieve the binding from its internal cache instance.  Since the cache is replicated, this will also retrieve an entry bound on another node via HA-JNDI.

2. Retrieve the binding from the local NamingServer.

3. Use RpcTreeCache RPC call to retrieve binding from local NamingServer on other nodes in the cluster.

4. If all lookups fail, return NameNotFoundException to caller.

HA-JNDI 5.x Transaction Support

By default, the cache is configured to support transactions.  Consequently an HA-JNDI client can incorporate bindings into a transaction, rolling back bindings as necessary.  This feature is provided via the use of JBossCache as the HA-JNDI store.

HA-JNDI 5.x Configuration

The ClusterTreeCache service instance used by HA-JNDI is configured in cluster-service.xml.  This service is a dependency of the HAJNDI service defined in the same file.   Note that the ClusterTreeCache service instance is shared by the HA-JNDI and DistributedState services so any changes made to the configuration will affect both services.

Reference Objects

The JNDI NamingServer implementation will throw NotContextException if an attempt is made to bind an object to a JNDI Reference object or lookup an object from a Reference object.  However if the Reference object is a dynamic federation (i.e., has an "nns" reference), the NamingServer will instead throw CannotProceedException.  In either case, HA-JNDI will throw NotContextException if the object is found in HA-JNDI.

HA-JNDI 4.x Implementation

Prior to JBoss AS 5, the HA-JNDI implementation was based upon the NamingServer implementation.  Each HA-JNDI node had its own NamingServer instance which handled binding and lookups; replication was accomplished via explicit RPC calls.  Lookups which failed in the internal NamingServer instance were then propagated to the local JNDI NamingServer on each node.