Summary: How to get objects in the same order in which they were written to the space.

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, 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.notify 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.

Return Value Method
boolean isFifo()
void setFifo(boolean enabled)

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.

Class Level FIFO Mode

POJO Based Class

Declaring a class as FIFO enabled done via the class Level fifo Annotation @SpaceClass:

@SpaceClass(replicate=true,persist=false,fifo=true)
public class Person
{
....
}

or when using the gs.xml via the fifo tag:

<gigaspaces-mapping>
	<class name="com.j_spaces.examples.hellospacepojo.Employee"	persist="false" replicate="false" fifo="true" >
	...
</gigaspaces-mapping>

Entry Based Class

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.

Return Value Method Usage
void setFifo(boolean fifo) Enables or disables the FIFO mechanism.

Creating FIFO Templates

POJO Based Class

Once the POJO declared as FIFO enabled all its instances are FIFO enabled.

Entry Based Class

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

Return Value Method Description
void setFifo(boolean fifo) Enables or disables the FIFO mechanism.
MyEntryClass template = new MyEntryClass();
template.setFifo(true);
MyEntryClass entry = (MyEntryClass)space.take(template , null , Lease.FOREVER);

Object Level FIFO Mode

POJO Based Class

Once the POJO declared as FIFO enabled all its instances are FIFO enabled.

Entry Based Class

Return Value Method Description
boolean isFifo() Returns FIFO status.

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.

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.

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).
Performing take operations in FIFO mode across different objects from different class types can be done via a dedicated "queue" class.
The "queue" will have FIFO based objects that contain the actual data object as payload (field within the queue class serializing the data) or to include the ID of the associated data object to be fetched once the object has been "consumed" from the "queue". Fetching space object can be done via its ID.
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

Return Value Method Description
String getClassName() Returns an invalid className.
boolean isFifoClass() Returns true if this class is defined as FIFO, otherwise false.

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

Return value Method Description
String getTemplateClassName() Returns an invalid template className.

Custom Client-Side FIFO-Based Notifications

Download the custom client-side FIFO-based notifications example and extract it under <GigaSpaces Root>\examples\Advanced\Messaging_Grid folder.

Implement the ComparableProvider interface (see the MessageProvider example) in order to call the NotifyDelgator listener using a custom order, and not a space event sequence.

To run the example, follow the instructions in the readme file.

The ComparableProvider includes the following methods:

public interface ComparableProvider <T extends Comparable<T>> {
    T getOrderValue(RemoteEvent event); // The order value ? you can get it from the entry
    T increment(T value); // how to increment
    T getStartValue(); // initial value
}

This aproach can be useful when you need to get FIFO-based notifications from a partitioned space, when you can provide the notifications order, based on application business logic (for example, in a market data application, this would be the feeder sequence number).

GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence