Overview

GigaSpaces supports class and field level annotations.

You can define common behavior for all class instances, and specific behavior for class fields.

This page is updated according to GigaSpaces version 5.1. If you are using GigaSpaces version 5.2, refer to the POJO Class & Field Level Annotations - 5.2 section.

Annotations

Class Level Decoration – @SpaceClass

Annotation Element Name	XML Space Mapping File Element Name	Type	Description	Default Value
replicate	replicate	boolean	When running in partial replication mode, a true value for this field will replicate all objects of this type to a target space or spaces.	false
persist	persist	boolean	When a space is defined as persistent, a true value for this annotation will persist objects of this type. For more details, refer to the Database Cache and Persistency section.	false
fifo	fifo	boolean	To enable FIFO-based notifications and take operations, this annotation should be true. For more details, refer to the FIFO operations section. .	false
converterType	converter-type	string	The object's original API – MAP, SPACE.	SPACE
IndexingMode	indexing-mode	String	Whether to use the class indexes list only, or to also include the super classes indexes. If the class does not have indexes defined, super class indexes will be used. Options: Instance – class indexes only. Hierarchy – class indexes and super classes indexes.	Instance

Field Level Decoration – @SpaceField

Field Level Decoration – @Key

Defines whether this field value is used when generating the Entry's UID. The field value should be unique – i.e., no multiple objects with the same value should be written into the space – each object should have a different field value. When writing an object into the space with an existing Key field value, an EntryAlreadyInSpaceException will be thrown. The Entry's UID is created based on the key field value.

Field level Decoration – @Nullable

Annotations Example

@SpaceClass (replicate=true,persist=false,fifo=true,converterType="space", indexing-mode="instance")
public class Person
{

        @SpaceField(index=true)
	private String getFirstName()
	{ ...
	}


        @Nullable(value="-1")
        public int getCount () {
         ...
        }

	@Key(autoGenerate=true}
	private String getLastName()
	{
		return lastName;
	}

}

Space Mapping XML Configuration File – gs.xml

The space mapping configuration file gs.xml allows you to define Space class meta data when using POJOs or Entry classes with getter or setters methods. Space mapping files are also required when using POJO objects with the CacheLoader. The gs.xml configuration file is loaded when the application and space are started. gs.xml files can be edited to include GigaSpaces specific attributes.

This file defines the client's POJO Data Access Object (DAO). For each field, there will be an indicator if it is PK, and if it needs to be calculated.

The *.gs.xml DAO configuration needs to reside in a <ROOT FOLDER>\config\mapping folder where the <ROOT FOLDER> should be part of the application classpath.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE gigaspaces-mapping PUBLIC 
"-//GIGASPACES//DTD GS//EN" "http://www.gigaspaces.com/dtd/1_0/gigaspaces-metadata.dtd">
<gigaspaces-mapping>
	<class name="com.j_spaces.examples.hellospacepojo.Employee"
		persist="false" replicate="false" fifo="false" >
		<property name="employeeID" index="true"
			key="true" auto-generate-key="false" />
		<reference
			class-ref="com.j_spaces.examples.hellospacepojo.Person" />
	</class>
	<class
		name="com.j_spaces.examples.hellospacepojo.Person"
		persist="false" replicate="false" fifo="false" >
		<property name="lastName" index="false"
			key="false" auto-generate-key="false" />
		<property name="firstName" index="false" />

	</class>
</gigaspaces-mapping>

Attributes

• <class> – a class-descriptor and the associated Java class ClassDescriptor encapsulate metadata information of concrete class.

  Attribute	Description
  name	Contains the full qualified name of the specified class. Because this attribute is of the XML type ID, there can only be one class-descriptor per class.
  persist	Indicates the transient field in the ExternalEntry. When a space is defined as persistent, a true value for this annotation will persist objects of this type. For more details, refer to the Database Cache and Persistency section.
  fifo	Indicates whether the POJO should be saved in FIFO order in the space. To enable FIFO-based notifications and take operations, this annotation should be true. For more details, refer to the FIFO operations section. .

• <property> – contains mapping information for a primitive-type attribute of a persistent class.

  Attribute	Description
  name	Holds the name of the persistent class attribute.
  index	Indicates which fields are indexed in the space. The first indexed member is used for hashing. Querying indexed fields speeds up read and take operations.
  key	Specifies if the field is marked as a primary key. Default value is false. It is possible to auto-assign primary key fields (see auto-generate-key below). A field must have a toString() method that cannot be changed in runtime.
  auto-generate-key	Specifies if the values for the persistent attribute should be automatically generated by the space. The field must be of type java.lang.String.

• <reference> – contains mapping info for an attribute of a class that is not primitive, but references another entity object.
• <class-ref> – contains the full qualified name of the specified class.

POJO Primary Key Settings

A POJO can be declared with or without a primary key. The primary key type can be java.lang.String or any other type, as long it implements the toString() method, where the toString() return value cannot change during the object's lifetime. The following table describes operations supported when using a primary key field.

Operation	Write	Take/Read	Update
Without primary key.
With primary key (auto-generator).		See warning below.
With primary key (no auto-generator).

Take or read operations with a primary key (auto-generator) are only supported when sending the PK field as not null or calling the toEntry() method with the parameter isIgnoreGenerateAutoPk = true.

If there is more than one primary key with an auto-generator, the converter generates a UID for each primary key. The UIDs are also set for the POJO primary key fields.

generateGsXml Utility – Generating the gs.xml File

In case a Hibernate class-to-database mapping configuration file (hbm) exists for the classes for which a space mapping configuration file gs.xml is required, a simple utility can be used to generate the gs.xml file from the hbm file.
The utility, generateGsXml, is located at <GigaSpaces Root>\bin.
The generated space configuration file gs.xml should be located at <ROOT FOLDER>\config\mapping folder where the ROOT FOLDER should be part of the application and space JVM CLASSPATH. GigaSpaces client and space load these files when the application and space are started.

generateGsXml Utility Options

Set the Environment variables as follows:

• POJO_CLASSPATH – The path for the POJOs class file.
• HIBERNATE_HOME – The path for the Hibernate configuration file and *.hbm files.

The generateGsXml command has the following parameters:

Examples

generateGsXml -beanName com.j_spaces.examples.hellospacepojo.SimpleBean  -outputDir D:\dev\gigaspaces\
generateGsXml -isHibernate true  -outputDir D:\dev\gigaspaces\ -hibernateConfigFile hibernate.cfg.xml