Template Matching

Template matching (a.k.a. Match by example) is a simple way to query the space - The template is a POJO of the desired entry type, and the properties which are set on the template (i.e. not null) are matched against the respective properties of entries of the same type in the space. Properties with null values are ignored (not matched).

Since by convention the default constructor usually initializes all the properties to null either implicitly or explicitly, in most cases it's enough to simply set the properties which should be matched, without bothering with explicitly setting null to the other properties. Note that setting two or more properties with non-null values provides an AND behavior.

Examples

The following examples assume the default constructor of Person initializes all its properties to null.

Read an entry of type Person whose firstName property is John:

Person template = new Person();
template.setFirstName("John");
Person person = gigaspace.read(template);

Read an entry of type Person whose firstName is John and lastName is Smith:

Person template = new Person();
template.setFirstName("John");
template.setLastName("Smith");
Person person = gigaspace.read(template);

If none of the properties are set, all the entries of the type are matched. For example, to count all entries of type Person:

int numOfPersons = gigaspace.count(new Person());

If the template class is null, all the entries in the space are matched. For example, to clear all entries from the space:

gigaspace.clear(null);

Indexes

GigaSpaces GigaSpaces includes a sophisticated built-in real-time indexing engine (regardless whether the space is persistent or not) that maintains a hash and btree like indexes for each indexed Space Class attribute. If you store a large number of Space objects from the same class type in the space, consider defining one or more indexes for attributes used with template matching or SQL Query. Defining indexes will improve the read,take,readMultiple,takeMultiple,clear,count operations response time significantly. Remember, indexes impact write and take operations response time, so choose your indexed fields carefully - each index has an overhead. GigaSpaces support index for equality , comparison (bigger/less than) queries and support Space Index for a specific field and a Compound Index for multiple fields. Indexes can be defined for space class root level object or for a nested field allowing you to query different type of objects ("join") using the same query without any performance penalty.

Inheritance Support

Template Matching support inheritance relationships, so that entries of a sub-class are visible in the context of the super class, but not the other way around. For example, suppose class Citizen extend class Person:

gigaSpace.write(new Person());
gigaSpace.write(new Citizen());
// Count persons - should return 2:
int numberOfPersons = gigaSpace.count(new Person());
// Count citizends - should return 1:
int numberOfCitizens = gigaSpace.count(new Citizen());

Partitioned cluster

When querying a partitioned cluster using a template, it is possible to use the routing property to control whether the query is broadcasted to the entire cluster or executed against a specific partition. For more information see Routing In Partitioned Spaces.

Primitive Types

Properties with primitive types pose a problem - a primitive type cannot be set to null. For example, suppose class Person has property age of type int, and we wrote the following piece of code which writes and reads a person:

// Create a person and write it to the space:
Person p1 = new Person();
p1.setAge(30);
gigaSpace.write(p1);
// Read person from space:
Person p = gigaSpace.read(new Person());

We expect p to hold the person we just wrote to the space, but in fact it will be null: since age is primitive it is implicitly initialized to 0 (zero) and cannot be set to null either implicitly or explicitly, which means we're actually matching for Persons whose age is 0 (zero).

To overcome this issue we can map a primitive value to null via the @SpaceProperty(nullValue) annotation. For example:

public class Person {
    private int age = -1;

    @SpaceProperty(nullValue="-1" )
    public int getAge() {
        return age;
    }
    public void setAge(int age) {
        this.age = age;
    }
    // The rest of the class is omitted for brevity.
}

We've indicated that -1 should be treated as null when performing template matching, and initialized age to -1 so users of Person class need not set it explicitly whenever they use it. Note that gs.xml can be used instead of annotations to specify metadata - for more information refer to POJO Metadata.

Nested Template Matching

Nested template matching is not supported - to match nested properties, collections and arrays use SQLQuery.