Summary: GigaSpace API Plain Old Java Object support - the
POJO. This section deals with the annotations and gs.xml mapping file decorations.
Space POJO Annotations and XML Mapping (gs.xml) File ElementsThe GigaSpaces API supports class and field-level decorations with POJOs. These can be specified via annotations on the space class source itself or external xml file accompanied with the class byte code files located within the jar/war. You can define common behavior for all class instances, and specific behavior for class fields. You may use the gs.xml files to decorate your Space classes as an alternative to Annotations or when you want to share the space decorations with .Net and C++ application accessing the same space objects.
Annotations
Class Level Annotation – @SpaceClass
Field Level Annotation – @SpaceProperty
example: @SpaceProperty(nullValue="-1" ) public int getEmployeeID() { return employeeID; } where -1 functions as a null value. Field Level Decoration – @SpaceIdThe space mapping file element name for @SpaceId is id (see below). Defines whether this field value is used when generating the Object ID. 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 is thrown. The Object ID is created, based on the id field value.
If autoGenerate is declared as false, the field is indexed automatically. If autoGenerate is declared as true, the field isn't indexed.
Field Level Decoration – @SpaceIndexQuerying indexed fields speeds up read and take operations. The @SpaceIndex annotation should be used to specify an indexed field. The @SpaceIndex has two attributes:type and path.
Examples:
The @SpaceIndex example
@SpaceClass public class Person { private String lastName; private String firstName; private Integer age; ... @SpaceIndex(type=SpaceIndexType.BASIC) public String getFirstName() {return firstName;} public void setFirstName(String firstName) {this.firstName = firstName;} @SpaceIndex(type=SpaceIndexType.EXTENDED) public String getAge() {return age;} public void setAge(String age) {this.age = age;} }
The @SpaceIndex using path example
@SpaceClass public static class Person { private int id; private Info personalInfo; private String description; //getter and setter methods ... // this defines and EXTENDED index on the personalInfo.socialSecurity property @SpaceIndex(path = "socialSecurity", type = SpaceIndexType.EXTENDED) public Info getPersonalInfo() { return personalInfo; } } public static class Info implements Serializable { private String name; private Date birthday; private long socialSecurity; //getter and setter methods }
Field Level Decoration – @SpaceVersionThis specifies a get method for holding the version ID. This field should be an int data type.
Field Level Decoration - @SpacePersistThis specifies a getter method for holding the persistency mode of the object overriding the class level persist declaration. This field should be of the boolean data type.
Field Level Decoration - @SpaceRoutingThe @SpaceRouting annotation specifies a get method for the field to be used to calculate the target space for the space operation (read , write...). The @SpaceRouting field value hash code is used to calculate the target space when the space is running in partitioned mode.
Field Level Decoration - @SpaceLeaseExpirationThe @SpaceLeaseExpiration annotation specifies a get and a set method for holding the timestamp of when the instance's lease expires (this is a standard Java timestamp based on the 1/1/1970 epoch). This property should not be populated by the user code. The space will populate this property automatically based on the lease time given by the user when writing the object. Here is how you can load an object into the space via the External Data source with a specific lease: @SpaceClass (persist=true) public class MyData { private long lease; ............. @SpaceLeaseExpiration public long getLease() { return lease; } public void setLease(long lease) { this.lease = lease; } } when loading the object into the space via the External Data source you should set this field lease value - with the example below the loaded object lease will be 10 seconds: public DataIterator<MyData> initialLoad() throws DataSourceException { List<MyData> initData = new ArrayList<MyData>(); // load the space with some data MyData obj = new MyData(); obj.setWhatEver(...); obj.setLease(System.currentTimeMillis() + 10000); initData.add(obj); return new MyDataIterator(initData); } Once an object has been loaded/written into the space you can also change the lease using the Gigaspace. write(T entry, long lease, long timeout, int modifiers) method. Field Level Decoration - @SpaceExcludeThe @SpaceExclude annotation instructs the client to ignore the fields using this annotation, so that they are not stored within the space.
Field Level Decoration – @SpaceStorageTypeThe @SpaceStorageType annotation should be used to specify how the property is stored in the space.
Field Level Decoration – @SpaceFifoGroupingPropertyThe @SpaceFifoGroupingProperty annotation should be used to define a space FIFO grouping property.
Field Level Decoration – @SpaceFifoGroupingIndexThe @SpaceFifoGroupingIndex annotation should be used to define a space FIFO grouping Index.
Constructor Level Decoration – @SpaceClassConstructorThe @SpaceClassConstructor annotation can be placed on a POJO constructor to denote that this constructor should be used during object instantiation. public class Data { private final Integer id; private final String data; @SpaceClassConstructor public Data(Integer id, String data) { this.id = id; this.data = data; } @SpaceId public Integer getId() { return id; } public String getData() { return data; } // notice that the lack of setters for id and data is this case is valid } POJO Class Example – Person and EmployeeThis example uses the @SpaceId, @SpaceRouting, @SpaceClass, replicate, persist, @SpaceVersion, @SpaceProperty and SpaceIndex annotations as part of the Person and Employee classes:
Person
package com.j_spaces.examples.hellospacepojo; import com.gigaspaces.annotation.pojo.*; @SpaceClass(replicate=true,persist=false) public class Person { private String lastName; private String firstName; public Person(){} public Person(String lastName, String firstName){ this.lastName = lastName; this.firstName = firstName; } @SpaceIndex(type=SpaceIndexType.BASIC) public String getFirstName(){return firstName;} public void setFirstName(String firstName) {this.firstName = firstName;} public String getLastName(){return lastName;} public void setLastName(String name) {this.lastName = name;} }
Employee
package com.j_spaces.examples.hellospacepojo; import com.gigaspaces.annotation.pojo.SpaceClass; import com.gigaspaces.annotation.pojo.SpaceId; import com.gigaspaces.annotation.pojo.SpaceRouting; import com.gigaspaces.annotation.pojo.SpaceVersion; @SpaceClass(replicate=true,persist=false) public class Employee extends Person { private Integer employeeID; private int versionID; public Employee(){} public Employee(Integer employeeID) { this.employeeID = employeeID; } public Employee(String lastName, Integer employeeID) { this.employeeID = employeeID; setLastName(lastName); } @SpaceId @SpaceRouting public Integer getEmployeeID(){return employeeID;} public void setEmployeeID(Integer employeeID) { this.employeeID = employeeID; } public String toString() { return super.toString() + ", \temployeeID: "+ employeeID ; } @SpaceVersion public int getVersionID() {return versionID;} public void setVersionID(int versionID) {this.versionID = versionID;} } Space Mapping XML File -- gs.xml The space mapping configuration file gs.xml allows you to define space class metadata when using a POJO class with getter or setter methods. Space mapping files are also required when using POJO objects with the ExternalDataSource interface. 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. gs.xml LocationThe *.gs.xml file should reside in same location as the related Pojo:
gs.xml ExampleWhen using the version, id and routing elements, place these in the gs.xml file in the following order:
Below is an example for an Employee class and a Person class XML configuration file named mapping.gs.xml: <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE gigaspaces-mapping PUBLIC "-//GIGASPACES//DTD GS//EN" "http://www.gigaspaces.com/dtd/7_1/gigaspaces-metadata.dtd"> <gigaspaces-mapping> <class name="com.j_spaces.examples.hellospacepojo.Employee" persist="true" replicate="true"> <version name="versionID" /> <id name="employeeID" auto-generate="false" /> <routing name="employeeID" /> <reference class-ref="com.j_spaces.examples.hellospacepojo.Person" /> </class> <class name="com.j_spaces.examples.hellospacepojo.Person" persist="true" replicate="true"> <property name="lastName" index="BASIC" /> <property name="firstName" index="BASIC" /> </class> </gigaspaces-mapping> The corresponding Employee class and a Person would be:
Person
public class Person { private String lastName; private String firstName; public Person(){} public Person(String lastName, String firstName) { this.lastName = lastName; this.firstName = firstName; } private String getFirstName(){ return firstName;} public void setFirstName(String firstName){this.firstName = firstName;} private String getLastName(){return lastName;} public void setLastName(String name){ this.lastName = name;} }
Employee
public class Employee extends Person { private Integer employeeID; private int versionID; public Employee(){} public Employee(Integer employeeID) { this.employeeID = employeeID; } public Employee(String lastName, Integer employeeID) { this.employeeID = employeeID; setLastName(lastName); } private Integer getEmployeeID(){ return employeeID; } private void setEmployeeID(Integer employeeID) {this.employeeID = employeeID;} private int getVersionID(){ return versionID; } private void setVersionID(Integer versionID) {this.versionID= versionID;} }
XML TagsClass Level Tags
Field Level Tags
User Defined Space Class FieldsYou may have user defined data types (non-primitive data types) with your Space class. These should implement the Serializable or Externalizable interface. The user defined class nested fields can be used with queries and can be indexed. See the Nested Properties and the Nested Properties Indexing section for details. TroubleshootingLoggingUse the com.gigaspaces.pojo.level = ALL as part of the logging file located by default at <GigaSpaces Root>\config\gs_logging.properties, to debug the POJO metadata load and conversion to space object. Having the <GigaSpaces Root> as part of the application CLASSPATH turns on the POJO debug activity at the client side. When the POJO logging is turned on, the following should appear at the client side console when a class is introduced to the space: FINEST [com.gigaspaces.pojo]: The annotation structure of class com.j_spaces.examples.hellospacepojo.Employee is : name = com.j_spaces.examples.hellospacepojo.Employee fieldNames = [firstName, lastName, employeeID, versionID] fieldPks = [employeeID] fieldAutoPkGen = [] fieldIndexs = [employeeID, firstName, lastName] hashBasedKey = [] version = [versionID] lazyDeserialization = [] payload = [] serializationTypeFields = {} defaultNullValueFields = {firstName=null, lastName=null} refClasses = [com.j_spaces.examples.hellospacepojo.Person] persist class = false persist instance = [] routing field name = [employeeID] timetolive = 9223372036854775807 fifo = false inheritIndexes = true includeProperties = IMPLICIT replicate true fieldTypes = null mappingType = space serializationType = 0 exclude = [] A converted object logging output looks like this: FINE [com.gigaspaces.pojo]: ExternalEntry after converter is: ClassName: com.j_spaces.examples.hellospacepojo.Employee Field Name: firstName Field Type: java.lang.String Field Value: first name1 Field Indexed: false Field Name: lastName Field Type: java.lang.String Field Value: Last Name1 Field Indexed: false Field Name: employeeID Field Type: java.lang.Integer Field Value: 1 Field Indexed: true Using The GUIUse the GS-UI Data Types View to examine the POJO meta data. Make sure the annotations/xml decorations have been introduced to the space correctly i.e. correct class name, field names, field types, indexes, routing field, replication mode and FIFO mode etc. |
![]() |
GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence |