Definition

A Data Grid Bean is an instance of a java.io.Serializable Java Class, where a). the methods of the said class conform to the Java Bean specification and b). the state and lifetime of the Data Grid Bean are managed by a Data Grid and not by an individual Java Virtual Machine that may have created the said Data Grid Bean.

Methods of Data Grid Beans are classified as being either Accessors or Mutators, where;

• Accessor methods do not change the state of a Data Grid Bean, are not void (they return a value) and have names that start with "get" or "is", and
• Mutator methods may change state of a Data Grid Bean, are typically void (but not necessarily so), and have names that start with "set" or otherwise (but not "get" or "is").

Usage

To specify that a standard Spring Bean is to be Data Grid Bean, set the Bean scope to be datagrid within the application xml configuration.

<bean id="ourCounter" class="Counter" scope="datagrid" />

To access the Data Grid Bean in Spring, use the getBean method of the ApplicationContext interface.

Counter ourCounter = (Counter)applicationContext.getBean("ourCounter");

Instantiation and Method Invocation Semantics

When a datagrid scoped Bean is encountered in a Spring xml Configuration, the following actions occur;

1. An instance of the specified Bean class is created and placed in a coherent distributed cache called "near-datagridbeans" using the specified Bean id. If a Bean with the specified id already exists in the said Cache, the said Bean is left unchanged.
2. A proxy is created for the said Bean that a). implements all of its interfaces (and methods), and b). injects an implementation of the com.tangosol.coherence.spring.datagrid.DataGridBean interface.
3. The generated proxy is registered with Spring using the specified bean id for use in a Spring Application.

When an Accessor method is invoked upon a proxy, the method is then invoked on a near-cached (local) copy of the Bean. This means all Accessor methods od Data Grid Beans are executed locally within the JVM of the Spring Application making the call.

When a Mutator method is invoked upon a proxy, the method is then invoked on the instance of the Bean directly in the distributed cache. This potentially remote invocation is performed using Coherence EntryProcessors - that a). ensure updates occur in a thread-safe manner without requiring cross-process and/or cross-network locking or data grid-wide synchronization and b). ensure that should their be failure of the caller or hosting Data Grid distributed caching service, the method invocation is recovered and invoked as expected on a backup of the said Bean.

Hence:

A Data Grid Bean is a proxy to a java.io.Serializable Bean instance that is stored in a non-expiring Coherence Distributed Cache (called near-datagridbeans).

Through the use of method interception, the proxy enables applications to use the Accessors and Mutators of cached Beans without needing to perform the usual 'get', 'put' or 'locking' cache operations. Additionally, the injected DataGridBean interface implementation permits applications to register real-time change listeners on the underlying cached Beans together with standard Coherence locking primitives (should they be required by an Application).

Overriding Default Accessor and Mutator Classification rules

While Data Grid Bean proxies observe the standard Bean rules for classifying methods as Accessors or Mutators, sometimes it may be necessary to override this behaviour and explicitly annotate Bean methods to further optimize method invocation. For example; if one or more methods fail follow the standard method naming conventions for Beans, the Data Grid Bean proxies may invocate a Mutator method locally in which case other Spring applications will not see the Bean update.

To explicitly annotate a Bean method as an Mutator, use the com.tangosol.coherence.spring.datagrid.annotations.Mutator annotation as follows;

@Mutator
    boolean getAndSet(...) {
        ...
    }

To explicitly annotate a Bean method as an Accessor, use the com.tangosol.coherence.spring.datagrid.annotations.Accessor annotation as follows;

@Accessor
    boolean hasMore(...) {
        ...
    }

The com.tangosol.coherence.spring.datagrid.DataGridBean interface

Each datagrid scoped Bean additionally supports the following interface (through Spring AOP injection).

public interface DataGridBean {

    public String getBeanId();

    public boolean lockNoWait();

    public boolean lock(long waitTimeMs);

    public void unlock();

    public void addUpdateListener(DataGridBeanUpdateListener listener);

    public void removeUpdateListener(DataGridBeanUpdateListener listener);
}

Access to this interface is acquired simply by casting to DataGridBean from the Bean instance itself.

DataGridBean dgb = (DataGridBean)ourCounter;

Data Grid Bean Update Events

Through the DataGridBean interface, all Data Grid Beans support the ability to register update event listeners.

Much like regular Bean event listeners, when a DataGridBeanUpdateListener is registered with a DataGridBean, it will be called back
whenever an update is made on the said Data Grid Bean, regardless of where it exists in a Data Grid.

The com.tangosol.coherence.spring.datagrid.DataGridBeanUpdateListener interface is defined as follows;

public interface DataGridBeanUpdateListener {

	public void onUpdate(DataGridBean dataGridBean);
}

The onUpdate method includes the specific DataGridBean instance that was updated for each invocation to enable a single listener to be registered for multiple Data Grid Beans.

The underlying implementation uses Coherence infrastructure to deliver the event notifications. This mechanism is extremely scalable, with wire-level (high) performance characteristics.

NOTE: Event delivery occurs asynchronously to the registered update listeners from the perspective of the process that updated the said Data Grid Bean(s).