Overview

GigaSpaces supports class and field level annotations.

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

New in GigaSpaces 5.2 This page is updated with changes made to POJO class and field level annotations in GigaSpaces 5.2. If you are using GigaSpaces 5.1, refer to POJO Class and Field Level Annotations - 5.1.

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.	true
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.	true
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
includeProperties	include-properties	String	IncludeProperties.IMPLICIT takes into account all POJO fields – even if a get method is not declared with a @SpaceProperties annotation, it is taken into account as a space field. IncludeProperties.EXPILICT takes into account only the get methods which are declared with a @SpaceProperties annotation.	IMPLICIT
mappingType	mapping-type	string	The object's original API – MAP (Map API) or SPACE (JavaSpaces).	SPACE
inheritIndexes	inherit-indexes	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: true – class indexes only. false – class indexes and super classes indexes.	true

Field Level Decoration – @SpaceProperty

Field Level Decoration – @SpaceId

The space mapping file element name for @SpaceId is id (see below).

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 id field value, an EntryAlreadyInSpaceException will be thrown. The Entry's UID is created based on the id's field value.

If auto-generate is declared as false, the field is indexed automatically. If auto-generate is declared as true, the field isn't indexed.

If autoGenerate is true, the field must be from type java.lang.String.

Field Level Decoration – @SpaceVersion

Field Level Decoration – @SpacePersist

Field Level Decoration – @SpaceRouting

The @SpaceRouting annotation routs the field value under this annotation to the relevant space. This is done using hash-based load-balancing.

Technology Preview The @SpaceRouting annotation is a technology preview and is not currently available for production.

The @SpaceRouting annotation can be used with the partitioned, replicated, and sync_to_backup schemas, except when working with the CacheLoader/CacheStore. This functionality will be available in future versions.

Field Level Decoration – @SpaceExclude

The @SpaceExclude annotation instructs to exclude the POJO field under this annotation and not save it in the space.

• When IncludeProperties is defined as IMPLICIT as part of the @SpaceClass annotation – @SpaceExclude should usually be used in this case, because IMPLICIT instructs to take all POJO fields into account.
• when IncludeProperties is defined as EXPLICIT – there is no need to use @SpaceExclude.
• @SpaceExclude can still be used even if IncludeProperties is not defined.

Annotations Example

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

	private String	lastName;
	private String	firstName;

	public Person()
	{
	}

	public Person(String lastName, String firstName)
	{
		this.lastName = lastName;
		this.firstName = firstName;
	}

	@SpaceProperty(index=IndexType.BASIC)
	private String getFirstName()
	{
		return firstName;
	}

	public void setFirstName(String firstName)
	{
		this.firstName = firstName;
	}

	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.

New in GigaSpaces 5.2 XML mapping can now be defined in the same package as the class (using the class name as the file prefix).

The fifo, replicate, and persist attributes must be defined (either true or false) as part of the class element. This is relevant in GigaSpaces version 5.2.

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


	</class>
</gigaspaces-mapping>

Attributes

• <class> – a class and the associated Java class ClassDescriptor encapsulate metadata information of a 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 info for a primitive-typed 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.

• <reference> – contains mapping information 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.
• <id> – defines whether this field value is used when generating the Entry's UID.

  Attribute	Description
  name	Specifies a get method that allows identification of the id element in the space.
  auto-generate	Specifies if the Entry's UID is generated automatically by the space when written into the space. If false, the field is indexed automatically, and if true, the field isn't indexed.

• <version> – saves the POJO's version in the space.

  Attribute	Description
  name	Specifies a get method for holding the version's ID.

• <persist> – allows you to specify whether a POJO is or isn't saved inside the space.

  Attribute	Description
  name	Specifies a get method for holding the persist flag.

• <routing> – routs the field under this element to the relevant space. This is done using hash-based load-balancing.

  Attribute	Description
  name	Specifies a get method that allows identification of the routing element in the space.

  Technology Preview The routing element is a technology preview and is not currently available for production.

  The routing element can be used with the partitioned, replicated, and sync_to_backup schemas, except when working with the CacheLoader/CacheStore. This functionality will be available in future versions.

• <exclude> – instructs to exclude the POJO field under this element and not to save it in the space.
  • If you specify a field name that exists as part of the property element, this field is excluded.
  • If the field name doesn't exist as part of the property element, this means that this field name is part of the Person class, and you do not want it to be saved in the space.

POJO Primary Key Settings

A POJO can be declared with or without an id. 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 id.
With id (auto-generator).		See warning below.
With id (no auto-generator).

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

If there is more than one id with an auto-generator, the converter generates a UID for each id. The UIDs are also set for the POJO id 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