Overview

The ability to have FIFO (First In, First Out) for space Entries is a critical requirement when building messaging systems on top of JavaSpaces or implementing master-worker patterns. Users should be able to get Entries in the same order in which they were written to the space. GigaSpaces supports non-ordered Entries and FIFO ordered Entries when performing space operations.

When a user performs a take operation in FIFO mode (the template fifo is enabled), the Entry's template includes null attributes and the space stores several matching Entries, the returned Entry will be sent back to the client based on its internal write time. The write time is determined based on a timestamp that ensures that a client receives Entries in FIFO order.

When registering for notification via the NotifyDelgator, the fifo argument should be true to instruct the space to deliver the notifications into the client in ordered manner. When the Notfiy registration done in fifo mode where will be one thread at the client side invoking the listerner notify method – as opposed to non fifo mode that might invoke the listener.notofy method in parallel via multiple threads at the client side.

SpaceFinder URL FIFO Parameter

In order to indicate that all template matching occurs according to FIFO, the space URL which is passed to the SpaceFinder should have the following parameter set:

URL?fifo

For example:

JavaSpace space = (JavaSpace)SpaceFinder.find ("jini://*/*/mySpace?fifo")

When calling the SpaceFinder.find with the fifo URL property, all templates and new Entries will be FIFO-enabled. In order to override this global behavior, we must set the setFifo(false) for every relevant template or new Entry class instance.

FIFO Proxy Mode

The IJSpace instance includes methods that allow you to set and get the proxy FIFO mode.

When calling the IJSpace.setFifo(true), all templates and new Entries will be FIFO-enabled. In order to override this global behavior, set the setFifo(false) for every relevant template or new Entry class instance.

Creating FIFO Templates

In order to create a template object that will indicate to the space that matching should use FIFO, call the setFifo(true) method.

MyEntryClass template = new MyEntryClass();
template.setFifo(true);
MyEntryClass entry = (MyEntryClass)space.take(template , null , Lease.FOREVER);

Entry FIFO Mode

Class FIFO Mode

In order to define a class and all its instances to be FIFO-enabled, the Entry class should implement the com.j_spaces.core.client.IMetaDataEntry interface, or extend the com.j_spaces.core.client.MetaDataEntry class. A call to the setFifo method should be done for the first Entry of that type written to the space. A better way of doing this is to call the setFIFO method at the class static initializer.

Take with FIFO

A take operation using FIFO might be critical when building a Point-to-Point (P2P) messaging system which needs to have message senders and receivers, where the receivers must get the sent messages in the exact order these have been sent by the senders. In order to ensure this queue-based approach, a take operation using a class with null attributes must be constructed to have the FIFO property enabled.

Notify with FIFO

In order to deliver notifications for registered templates back to the subscribers in FIFO mode, the template used at the NotifyDelegator must be FIFO-enabled.

New in Version 5.1 Registering for notifications on the take operation in FIFO mode is supported in GigaSpaces version 5.1 and onwards.

Persistent Space in FIFO Mode

When a space includes FIFO-enabled classes and is defined as persistent, the persistent store (RDBMS) includes the relevant information that ensures FIFO. This might impact the performance, since an additional index is created for each table storing the Entry Class instances.

read, readMultiple, takeMultiple with FIFO

When using the read operation in FIFO mode - ie. the template that extends MetaDataEntry is FIFO enabled, or the space proxy is FIFO enabled; the Entry that is returned is the first Entry written to the space that matches the constructed template.

When using the readMultiple or takeMultiple with a template that has FIFO mode enabled, the returned array will be ordered according to the time the Entries are written to the space.

You may read a huge amount of Entries in FIFO mode in a scalable manner via the readMultiple, operation using the ExternalEntry ReturnOnlyUids mode, iterating through the returned UIDs array, and getting the relevant Entry. The returned array of UIDs is organized according to the time the corresponding Entries are written to the space.

FIFO and Transactions

– When executing a take and write operations with an Entry object having UID access methods without using a transaction , then the object is placed at the back of the FIFO queue.
– When executing a take and write operations with an Entry object having UID access methods having the same UID under the same transaction, then the object is not sent to the back of the FIFO queue (the entry order within the FIFO queue is preserved) and an update operation is eventually performed.
– When executing a take and write operations with an Entry object having UID access methods having the same UID under the same transaction where the Entry UID is set to null prior the write operation , a new Entry will be inserted into the space and the written Entry will be placed at the back of the FIFO queue.

Limitations

– FIFO is supported only at the class level across the different class instances from the same class type and not across different instances from different classes.
– FIFO is not supported across inherited classes - i.e. entries from different inherited classes cannot be taken, read or notified in FIFO mode.
– FIFO is not supported across different spaces - i.e. you cannot perform take ,read or notify in FIFO mode across different spaces (partitioned space).

Custom Client-Side FIFO-Based Notifications The custom client-side FIFO-based notifications example below allows you to receive notifications based on application business logic.

Exceptions

com.j_spaces.core.FifoOperationException is the parent exception class of all Fifo exceptions.

com.j_spaces.core.InvalidFifoClassException

This exception is thrown during a write operation, when FIFO mode has already been defined in the Entry class, and a later write operation defines a different FIFO mode.

Methods

com.j_spaces.core.InvalidFifoTemplateException

This exception is thrown if read or take operations are executed in FIFO mode, but the template class FIFO mode has already been set to non-FIFO mode.

Methods

Custom Client-Side FIFO-Based Notifications

When having the need to receive FIFO-based notifications with a partitioned space, where you can provide the notification order, based on the application business logic (for example, in a market data application, this would be the feeder sequence number) you may want to consider having customized FIFO notification ordering.

The example below illustrates customized FIFO notification ordering.
To run the example download the custom client-side FIFO-based notifications example and extract it under <GigaSpaces Root>\examples\Advanced\Messaging_Grid folder.

Full running instructions included with the readme file located at part of example.

The MessageProvider class implements the ComparableProvider interface. This allows the NotifyDelgator listener to use the custom based FIFO notification ordering and not the default space event sequence.

Please note the ComparableProvider includes the following methods:

public interface ComparableProvider <T extends Comparable<T>> {
    T getOrderValue(RemoteEvent event); // The order value
    T increment(T value); // how to increment
    T getStartValue(); // initial value
}