JavaSpaces POJO

  Search Here
Searching GigaSpaces XAP/EDG 6.5 Documentation

                                               

This page is specific to:
GigaSpaces 6.5

If you're interested in another version, click it below:
• GigaSpaces 5.x
• GigaSpaces 6.0

Overview

GigaSpaces JavaSpaces POJO support allows you to use JavaBean classes as space domain classes, and perform space operations using these objects. POJO domain Classes should follow rules similar to the ones defined by JPA, Hibernate and other domain class frameworks.

GigaSpaces POJO:

  • Do not implement the net.jini.core.entry interface.
  • Follow the JavaBeans specification.
  • Have private fields.
  • Have primitive types (int, boolean, etc.) fields.
  • Have getter and setter methods.
  • Include space class metadata decorations (indexed fields, affinity-keys, persisted mode, etc.).

You can define space classes metadata by class and field level decorations. These can be defined via annotations or XML configurations files.

This page deals with the POJO class as a space domain class, used to model the space and store application data into the IMDG.

POJO classes deployed as services into the Service Grid are described in the OpenSpaces Events Component - Data Event Listener and OpenSpaces Remoting Components sections. In these cases, the POJO class is used to process incoming data or is invoked remotely.

POJO as Space Domain Class

When using a POJO as a space domain class, follow these guidelines:

  • A POJO class must implement a default (zero argument) constructor.
  • A POJO class cannot implement the net.jini.core.entry interface; otherwise, it is treated differently.
  • A POJO class should have space class metadata decorations using annotations or a gs.xml file with relevant metadata (indexed field list, version field, FIFO mode, persistency mode, primary key (i.e. id)). If neither are provided, the defaults are presumed. (The default settings might not always match your needs.)
  • Getter/setter methods for fields that you want to be persisted in the space.
  • Non-primitive fields must implement Serializable or Externalizable. For example, if you are using a POJO class that contains a nested class.
  • When performing matching/queries using primitive fields (int , long , double, etc.) the nullValue annotation or null-value tag must be specified with relevant values to function correctly. 
    @SpaceProperty(nullValue="-1")
public int getEmployeeID()
{
	return employeeID;
}
  • The UID can be determined using the @SpaceId annotation or the id tag.
  • When using POJOs, write operation using the UpdateModifiers.UPDATE_OR_WRITE mode by default. This means that when the space already includes an object with the same UID (@SpaceId with the same value), the POJO is updated, and new object is not inserted.
  • When using SpaceId(autoGenerate=true), the UID is stored inside the SpaceId field, causing an overhead when indexed.
  • TokenQuery is not supported with POJOs.
  • POJO space mapping files gs.xml files can be loaded from:
    • <CLASSPATH>\config\mapping folder, or
    • The same package where the class file is located using the format <<Class Name>>.gs.xml.
  • A null value as template is not supported. Use new Object() instead.
  • FIFO mode is supported only at the POJO class level. You can't specify a template with fifo=false and write an object with fifo=true. You should use a different space proxy in such cases.
  • A POJO class must implement the Serializable or Externalizable interface if used as a parameter for a remote call (OpenSpaces remoting).
  • When using the org.openspaces.core.GigaSpace interface, you can use generics when conducting space operations.
  • The @Spaceid annotation or id tag must be declared when performing update operations.
  • To persist a POJO object using the ExternalDataSource , Mirror Service, JDBC Storage Adapter, or indexed file options, the persist decoration must have the value true.
  • When a space configured to use the ExternalDataSource the @Spaceid annotation or id tag auto-generate attribute should be set to false. The object must include a unique value with the SpaceId field when written into the space.
  • The SpaceId field can be java.lang.String type or any other type that implements the toString() method.
  • All net.jini.core.entry.Entry based classes meta data methods are not supported with with POJO based classes. These include: _setEntryInfo() , __getEntryInfo() , __setEntryUID() , __getEntryUID() ,_getSpaceIndexedFields(). With POJO based space domain classes meta data declared using relevant annotations or xml tags.

Batch Operations

  • Batch operations boost performance, since they interact with the server in one call and retrieve the result from the space with one space operation. This allows the client and server to utilize the network bandwidth in efficient manner - in some cases, up to 10 times faster compared to single based operations.
  • readMultiple should be handled with care since it can return a large data set (potentially all space data). This might cause an out of memory error in the space and client process. You should use the GSIterator to return the result in batches in such cases.
  • Destructive batch operations (take , write , update) should be performed with transactions – this allows the client to roll back the space to its initial state before the operation was started, in case of a failure.
  • When calling writeMultiple or updateMultiple, make sure null values are not part of the passed array.
  • When using writeMultiple for , you should verify that duplicated entries (with the same ID) do not appear as part of the passed array, since the identity of the object is determined based on its ID and not based on its reference. This is extremely important with an embedded space, since writeMultiple injects the ID value into the object after the write operation.
  • readMultiple and takeMultiple do not support timeout operations. The simple way to achieve this is by calling the read operation with the proper timeout, and if non-null values are returned, perform the batch operation.

Code Examples

Space operations with POJO objects can be conducted using the org.openspaces.core.GigaSpace interface or the com.j_spaces.core.IJSpace interface.

The examples below using the org.openspaces.core.GigaSpace interface.

Writing and Reading POJOs

Getting Space proxy:

UrlSpaceConfigurer urlSpaceConfigurer = new UrlSpaceConfigurer("jini://*/*/mySpace");
GigaSpace space = new GigaSpaceConfigurer(urlSpaceConfigurer.space())
	.defaultTakeTimeout(1000)
 	.defaultReadTimeout(1000)
 	.gigaSpace();

The following writes an Employee object and reads it back using a simple template:

GigaSpace space;
Employee employee = new Employee("Last Name", new Integer(32));
employee.setFirstName("first name");
space.write(employee);
Employee template = new Employee();
Employee result = space.read(template);

Registering for Notifications

The following register for notifications:

GigaSpace space;
SimpleNotifyEventListenerContainer
	notifyEventListenerContainer = new SimpleNotifyContainerConfigurer(space)
	.template(new Employee())
	.eventListenerAnnotation(new Object()
		{
		@SpaceDataEvent
		public void eventHappened(Object event) {
		System.out.println("onEvent called Got" + event);
	   	}
	})
	.fifo(true)
	.notifyWrite(true)
	.notifyUpdate(true)
	.notifyContainer();

Writing batch of objects

When writing batch of objects into the space these should be placed into an array to be used by the GigaSpace.writeMultiple operation. The returned array will include corresponding LeaseContext object.

GigaSpace space;
Employee emps[] = new Employee[2];
emps[0] = new Employee("Last Name A", new Integer(10));
emps[1] = new Employee("Last Name B", new Integer(20));
LeaseContext[] leaseContexts = space.writeMultiple(emps);
for (int i = 0;i<leaseContexts.length ; i++)
{
	System.out.println ("Object UID " + leaseContexts[i].getUID() + " inserted into the space");
}

Reading objects using SQLQuery

The following query the space using SQL:

GigaSpace space;
String querystr	= "employeeID=1 or employeeID=2";
SQLQuery query = new SQLQuery(Employee.class.getName(), querystr);
Employee results[] = space.readMultiple(query , 10000);
Constructing SQLQuery objects is a relatively expensive operation. You should not construct these with every space query operation. Instead, it is recommended to construct it once, and then use it with dynamic query options: SQLQuery.setParameters and SQLQuery.setParameter.

Clearing objects

You can use the SQLQuery with the GigaSpace.clear to remove objects from the space:

GigaSpace space;
String querystr	= "age>70";
SQLQuery query = new SQLQuery(Employee.class.getName(), querystr);
space.clear(query);
When using the SQLQuery with bigger/less than queries turn on the extended indexing.

Updating an Object

The GigaSpace.write with the UpdateModifiers.UPDATE_ONLY modifier should be used to explicitly perform an update operation. The UpdateModifiers.UPDATE_OR_WRITE is the default mode with write operations. This means that subsequent calls to the write operation with an object with identical SpaceId will result an update operation - i.e. new object will not be inserted into the space.

The GigaSpace.write has few activity modes - With each mode the return object options are different.:

  1. Inserting or updating an existing object - The UpdateModifiers.UPDATE_OR_WRITE modifier should be used. This is the default mode.
  2. Inserting a new object into the space - The UpdateModifiers.WRITE_ONLY modifier should be used.
  3. Updating an existing object - The UpdateModifiers.UPDATE_ONLY modifier should be used.
    • when the UpdateModifiers.UPDATE_OR_WRITE modifier is applied the following returns:
      • For successful operation:
        • LeaseContext - The LeaseContext.getObject() will return:
          • null - if new object inserted (write operation)
          • The previous version of the object (update operation)
    • For unsuccessful operation:
  • when the UpdateModifiers.UPDATE_ONLY modifier is applied the following returns:
    • For successful operation:
      o LeaseContext - Where the LeaseContext.getObject() will return the previous version of the object.
    • For unsuccessful operation:
      o null - if timeout occurred. This means the object is locked under another transaction.
      o an Exception object is thrown. Options are:
      • EntryNotInSpaceException - in case the object does not exists in space.
      • SpaceOptimisticLockingFailureException. Thrown only when running in Optimistic Locking mode. This Exception includes the existing version id of the object within the space and the client side version id of the object. In this case you should read the object again and retry the update operation. See the Optimistic Locking for more details.

When updating an object you can specify 0 (ZERO) as the lease time. This will instruct the space to use the original lease time used when the object has been written into the space.

UPDATE_OR_WRITE Example:

try
{
	LeaseContext ret = space.write(employee ,/*lease*/  0 ,/*timeout*/  1000 , UpdateModifiers.UPDATE_OR_WRITE);
	if ( ret.getObject() == null)
	{
		//  successful write
	}
	if (ret.getObject() instanceof Employee) 
	{
		//  successful update
	}
}
catch (UpdateOperationTimeoutException uote)
{
	// Object is locked - unsuccessful update
}

WRITE_ONLY Example:

try
{
	LeaseContext ret = space.write(employee ,/*lease*/  0 ,/*timeout*/  1000 , UpdateModifiers.WRITE_ONLY);
	if ( ret.getObject() == null)
	{
		//  successful write
	}
}
catch (EntryAlreadyInSpaceException eainse)
{
	// Object already exists - unsuccessful write
}

UPDATE_ONLY Example:

try
{
	LeaseContext ret = space.write(employee ,/*lease*/  0 ,/*timeout*/  1000 , UpdateModifiers.UPDATE_ONLY);
	if ( ret == null)
	{ 
		// Object is locked - unsuccessful update
	}
	else if (ret.getObject() instanceof Employee) 
	{
		//  successful update
	}
}
catch (EntryNotInSpaceException enise)
{
	// Object not in space - unsuccessful update
}
catch (SpaceOptimisticLockingFailureException solfe)
{
	// Client holds wrong version of the object - unsuccessful update. We need to read it again and issue the update call again.
}

Updating batch of Objects

The GigaSpace.updateMultiple returns array of objects which correspond to the input object array. The returned object element can be either one of:

  • when the UpdateModifiers.UPDATE_OR_WRITE modifier is applied the following returns:
    • For successful operation:
      o null - if new object inserted (write operation)
      o The previous version of the object (update operation)
Since the GigaSpace.updateMultiple in UpdateModifiers.UPDATE_OR_WRITE mode does not support timeout based updates, there is no way to identify if an updated object is already locked under a transaction - i.e. the UpdateOperationTimeoutException is not returned as part of the returned array elements.
With a transactional system it is recommended to perform batch updates using the UpdateModifiers.UPDATE_ONLY modifier.

UPDATE_ONLY Example:

GigaSpace space;
Employee employees[] = space.readMultiple(query , 10000);
	Object retUpdateMulti[] = space.updateMultiple(employees ,/*leases*/ new long[results.length],UpdateModifiers.UPDATE_ONLY);
	
for (int i = 0;i<retUpdateMulti ; i++)
{
	if  (retUpdateMulti[i] == null ) {
		//  unsuccessful update
		break;
	}
	else if  (retUpdateMulti[i] instanceof Exception) {
		//  unsuccessful update
		if (retUpdateMulti[i] instanceof EntryNotInSpaceException)
		{
		...
		}
		
		else if (retUpdateMulti[i] instanceof SpaceOptimisticLockingFailureException)
		{
		...
		}
		
		
		break;
	}

	else if  (retUpdateMulti[i] instanceof Employee ) {
		//  successful update
	}
}

POJO Annotations and XML Space Mapping File Elements

GigaSpaces supports class and field-level annotations. You can define common behavior for all class instances, and specific behavior for class fields.


GigaSpaces 6.5 Documentation Contents (Current Page in Bold)

    Java

    C++

    .NET

    Middleware Capabilities

    Configuration and Management

Add GigaSpaces wiki search to your browser search engines!
(works on Firefox 2 and Internet Explorer 7)

Labels