Overview

This section discusses client applications that use the JavaSpace API to read Entry data from a space and, if the data is not found in the space, require the space to read from a different datasource, which can be a database or any other type of external application. The CacheLoader Interface provides the connection to the datasource.
For each read method of the JavaSpace API called in the client application (relevant for the read, take, readMultiple, takeMultiple operations), there must be a corresponding user implementation of CacheLoader Interface methods. The following sections describe in detail how to code these implementations with examples of each.

In case the external data source is a database, the HibernateCacheLoaderImpl/HibernateCacheStoreImpl driver may be used as an alternative that does not require any user implementation.

This section also includes client applications that use ExternalEntry when accessing the space. This is mostly relevant for C++ , C# , JMS and JDBC applications that use ExternalEntry objects implicitly.
The examples of the CacheLoader method implementation in this section use the JDBC API to access RDBMS.

A space write operation using UIDs calls the CacheLoader methods implicitly to make sure the database does not have relevant record with same primary key data. Space update operations also call the CacheLoader implicitly to load and lock the database record.

The GigaSpaces JavaSpaces API provides two different ways of specifying the Entry to read: by template or by SQLQuery.

RegExQuery is not supported by the CacheLoader.

Although the following sections discuss Entry classes, POJO classes are also supported when using JavaSpaces API. All Entry or POJO classes should have getter/setters methods and gs.xml or annotations describing the meta data required (index list , primary key , type).

A full running example demonstrating the CacheLoader implemented using JDBC is located under: <GigaSpaces Root>\examples\Advanced\Data_Grid\Database-Integration\jdbcCaheStore. A full running example demonstrating the CacheStore implementation using Hibernate is located under: <GigaSpaces Root>\examples\Advanced\Data_Grid\Database-Integration\HibernateCaheStore.

To enable logging for the CacheLoader\Store, edit the <GigaSpaces Root>\config\gs_logging.properties file and set the persistent level to CONFIG or FINER. For more details, refer to the Settings & Configuration section.

Matching by Template

This section discusses how to read object data from the space or data source using template input. A template is an object, passed as a parameter in the read method, whose attributes can be fixed or null ("wild card"). The space or data source is searched until an object whose values match those of the template is found. For a multiple object read operation, the search attempts to match the required number of objects.
There are three different cases, depending on the values of the template and the JavaSpace read method:

• Reading a single Entry using a null-valued template.
• Reading a single Entry using a non null-valued template.
• Reading multiple Entries using a template.

Reading a Single Entry Using a Null-Valued Template

This section describes how to read or take a single Entry object using a null-valued template. A null-valued template is a an Entry object whose field values are all null. Any object from the template class or its sub-classes that is stored in the space matches this template and is a candidate to be returned back to the client.

The JavaSpaces.take operation execution is broken down at the space level into two separate calls: one to the CacheLoader.load method and one to the CacheStore.erase method. This section focusses on the CacheLoader.load call. The write-through section discusses the CacheStore.erase method.

The figure above illustrates how a client application reads a single Entry from the space that matches a given template where the actual data is loaded from a database or other external application.
The operation proceeds in two stages:

1. The client application calls the JavaSpace API read or take methods, passing the template with null values for all attributes as first parameter.
   The client application call would look like this:

   Person person = (Person)JavaSpace.read(new Person(), null, timeout);

2. The JavaSpace API initiates data lookup in the space for a matching Entry. Since there are no non-null field values, the first Entry found from the Person class or its sub-classes instances that matches the template is returned (note that Entries under a transaction cannot be returned). If no such Entry is found, the CacheLoader Interface method load is called by the space, passing a parameter IGSEntry that encapsulates the original template data. The load method extracts the relevant data from the IGSEntry (such as class name) and, using the JDBC API, constructs a database SQL Query that gets the required record data from the database. The first object satisfying the query is converted to an IGSEntry object and returned back to the space. The space returns the result Entry in Entry format to the client implicitly.

   You can construct an IGSEntry object using the conversion methods or by creating an ExternalEntry object that is the concrete IGSEntry class.

CacheLoader.load Implementation

The CacheLoader Interface method load is called by the space and has the following signature:

IGSEntry loadedObject = load (IGSEntry template)

The original template object can be extracted from the passed IGSEntry using:

Object originalTemplate = getConverter.toObject(IGSEntry)

The data from the individual properties of the Entry object can now be extracted and a JDBC Query can be created. The JDBC call constructs the result loaded object that should be converted to IGSEntry using the following conversion call:

getConverter().toIGSEntry(loadedObject);

Sample Code

Client application: JavaSpaces API

Person person1 = space.read(new Person(), null, timeout);

CacheLoader implementation: load method:

MyCacheLoader extends AbstractCacheLoader
{
	public Object load(Object key) {

		Object values[] = null;
		Object loaded_object = null;

		try {
			Object myObject = getObject((IGSEntry) key);
			int keyValue = 0;
			if (myObject instanceof Person) {
				Person person = null;
				// This is the template we got - must have ID
				person = (Person) myObject;
				keyValue = person.getId().intValue();
				// Constructing the query
				Connection con = getConnection();

				PreparedStatement stP = con.prepareStatement(
						"select * from  "
						+ tableNames.get(((IGSEntry) key)
						.getClassName()) + " where ID = ? ");
				stP.setInt(1, keyValue);

				ResultSet rs = stP.executeQuery();
				int sz = rs.getMetaData().getColumnCount();

				values = new Object[sz];
				while (rs.next()) {
					for (int i = 0; i < sz; i++) {
						values[i] = rs.getObject(i + 1);

					}
					// here we construct the loaded Person object
					loaded_object = new Person(String.valueOf(values[0]),
							String.valueOf(values[1]), Integer.
							valueOf(String
									.valueOf(values[2])));
					break;
				}
				rs.close();
				rs.close();
				con.close();
			}
		} catch (Exception e) {
			e.printStackTrace();
			throw new RuntimeException(e);
		}
		return getConvertor().toIGSEntry(loaded_object);
	}

Reading a Single Entry Object for a Non Null-Valued Template

This section describes how to read a single Entry object using a non null-valued template. A non null-valued template is an Entry object one of whose field values are non-null and has a specific value. Any object from the template class or its sub-classes that is stored in the space and whose value for this field matches the given template is a candidate to be returned back to the client. Null field values in the template are ignored in the search.

Indexed fields speed up the search. Performing matching using non-indexed fields when the space has a large amount of instances of the template class or its sub-classes can consume a large amount of memory and slow down the search.

The figure illustrates how a client application reads or takes a single Entry from the space that that matches a given template where the actual data is loaded from a database or other external application.
The operation proceeds in two stages:

1. The client application calls the JavaSpace API read or take methods, passing the template with non-null values for some attributes and null values for other attributes as first parameter.
   The client application call would look like:

   Person person = (Person)JavaSpace.read(new Person("john","doe", null), null, timeout);

2. The JavaSpace API initiates data lookup in the space for a matching Entry. The first Entry found from the Person class or its sub-classes instances that matches the template is returned (note that Entries under a transaction cannot be returned). If no such Entry is found, the space calls either the CacheIteratorFactory.iterator method, if implemented, or, if not implemented, it calls the CacheLoader.loadAll method, passing a CacheQuery object within a Map collection (collection with one object) that encapsulates the original template data as a parameter. The called method extracts the SQL Query object from the CacheQuery and, using the JDBC methods, gets the required record data from the database. The first object satisfying the SQLQuery is converted to an IGSEntry object and returned back to the space. The space returns the result Entry in Entry format to the client implicitly.

   You can construct an IGSEntry object using the conversion methods or by creating an ExternalEntry object that is the concrete IGSEntry class.

CacheIteratorFactory.iterator Implementation

The CacheIteratorFactory.iterator method is called by the space and has the following signature:

Iterator iterator = CacheIteratorFactory.iterator (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery by:

SQLQuery sqlQuery = CacheQuery.getQuery();

The SQL Query can now be used to retrieve the data sought using the JDBC API.

CacheLoader.loadAll Implementation

The CacheLoader Interface load method is called by the space and has the following signature:

Map persons = loadAll (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery by:

SQLQuery sqlQuery = CacheQuery.getQuery()

The SQL Query can now be used to retrieve the data sought using the JDBC API.

Iterator Method vs. loadAll Method

The following considerations apply when choosing between implementing the CacheIteratorFactory interface or the CacheLoader.loadAll method for the CacheLoader:

• The CacheIteratorFactory.iterator and CacheLoader.loadAll methods retrieve data from the database in different ways. The CacheIteratorFactory.iterator retrieves the data from the data set one by one until it finds the data sought; the CacheLoader.loadAll method retrieves all data set elements from the database , searches for matching entries until it finds the data sought.
  As a result, for retrieving a small amount of data, the loadAll method should be preferred to the Iterator method since it will consume less memory and time. For a large amount of data, the Iterator method will get data from the database more efficiently.
• During a read, the CacheIteratorFactory can return several candidates back into the space that can be used when one of them is locked by a transaction.
  For example: When a user performs a take operation in a transaction and there is one matching object in the space, that object is locked pending completion of the transaction. If another client now tries to perform a take with a template that matches the object that was locked, but another matching object exists in the database, the CacheIteratorFactory.iterator will allow you to return the object from the database to the client. (The CacheIteratorFactory.iterator might return the locked object as well as other objects – but the locked object will be ignored and one of the remaining matching objects will be returned to the client).

The following table shows when each method is used according to the client API call:

Sample Code

In client application: JavaSpaces API Using Entry objects:

Person person = (Person)space.read(new Person("john","doe", null), null, timeout);

CacheLoader implementation: implements CacheIteratorFactory:

public class MyCacheLoaderImpl extends AbstractCacheLoader implements CacheLoader,CacheIteratorFactory
		{

	public CacheIterator iterator(CacheQuery cacheQuery) {
		Object query = cacheQuery.getQuery();
		String classname = null;
		System.out.println(" ********* iterator Called ********* ");
		String querystr = null;
		// null template
		PreparedStatement stP = null;
		Connection con = null;
		try {
			con = getConnection();
		} catch (SQLException e) {
			throw new RuntimeException(e);
		}

		if (query instanceof IGSEntry) {
			IGSEntry igsentry = (IGSEntry) query;
			classname = igsentry.getClassName();

			if (classname.equals("java.lang.Object")) {
				System.out.println("HERE YOU CAN LOAD DATA
				INTO THE SPACE WHEN IT IS STARTED!");
			}

			if (!tableNames.containsKey(igsentry.getClassName())) {
				System.out.println("Do not have mapping for class "
						+ igsentry.getClassName());
				return null;
			}
			querystr = "select * from "	+ tableNames.get(igsentry.getClassName());
			try {
				con.prepareStatement(querystr);
			} catch (SQLException e) {
				// TODO Auto-generated catch block
				e.printStackTrace();
			}
			System.out.println("IGSEntry " + querystr);
		}

		// null template or SQLQuery used
		else if (query instanceof SQLQuery) {
			SQLQuery sqlquery = (SQLQuery) query;
			classname = sqlquery.getClassName();
			if (!tableNames.containsKey(sqlquery.getClassName())) {
				System.out.println("Do not have mapping for class "	
				+ sqlquery.getClassName());
			}

			try {
				stP = buildQuery(cacheQuery, con);
			} catch (SQLException e1) {
				// TODO Auto-generated catch block
				e1.printStackTrace();
			} catch (UnusableEntryException e1) {
				// TODO Auto-generated catch block
				e1.printStackTrace();
			}
			
			ResultSet rs = null;
			try {
				System.out.println("***** Iterator Query:" );
				rs = stP.executeQuery();
			} catch (SQLException e) {
				e.printStackTrace();
				throw new RuntimeException(e);
			}
			return new CacheLoaderIterator(con, rs, classname);
		}
		return null;
	};

	// The CacheLoaderIterator used by the CacheIteratorFactory.iterator
	public class CacheLoaderIterator implements CacheIterator {
		String className = null;
		ResultSet result = null;
		Connection con = null;
		
		public CacheLoaderIterator(Connection con , ResultSet result, String className) {
			this.result = result;
			this.className = className;
			this.con = con;
		}

		public boolean hasNext() {
			try {
				
				return result.next();
			} catch (SQLException e) {
				e.printStackTrace();
				return true;
			}
		}

		public Object next() {
			try {
				Object obj = null;
				if (className.equals(Person.class.getName())) {
					Integer id = new Integer(result.getInt(3));
					obj = new Person(result.getString(1), result.getString(2),
							id);
				}
				IGSEntry value = getConvertor().toIGSEntry(obj);
				return value;
			} catch (Exception e) {
				return null;
			}
		}

		public void remove() {
			throw new NotImplementedException();
		}

		public void close()
		{
			try {
				result.close();
				con.close();
			} catch (SQLException e) {
				e.printStackTrace();
			}
		}
	}
}

CacheLoader implementation: method loadAll:

public class MyCacheLoaderImpl extends AbstractCacheLoader implements CacheLoader{

	public Map loadAll(Collection keys) {
		System.out.println(" ********* loadAll Called ********* ");
		HashMap map = new HashMap();
		Iterator keyIter = keys.iterator();
		PreparedStatement stP = null;
		Connection con = null;
		try {
			con = getConnection();
		} catch (SQLException e1) {
			// TODO Auto-generated catch block
			e1.printStackTrace();
		}

		while (keyIter.hasNext()) {
			CacheQuery exprationEntry = (CacheQuery) keyIter.next();
			Object query = exprationEntry.getQuery();
			String querystr = null;
			// null template
			if (query instanceof IGSEntry) {
				IGSEntry igsentry = (IGSEntry) query;
				if (!tableNames.containsKey(igsentry.getClassName())) {
					System.out.println("Do not have mapping for class "	
					+ igsentry.getClassName());

					if (igsentry.getClassName().equals("java.lang.Object")) {
						System.out.println("HERE YOU CAN LOAD 
						DATA INTO THE SPACE WHEN IT IS STARTED!");
					}
					// return empty map - indicates no objects loaded from database
					return map;
				}
				querystr = "select * from "	+ tableNames.get(igsentry.getClassName());
				try {
					stP = con.prepareStatement(querystr);
				} catch (SQLException e) {
					// TODO Auto-generated catch block
					e.printStackTrace();
				}
			}
			// non null template or SQLQuery used
			if (query instanceof SQLQuery) {
				SQLQuery sqlquery = (SQLQuery) query;
				if (!tableNames.containsKey(sqlquery.getClassName())) {
					System.out.println("Do not have mapping for class "
					+ sqlquery.getClassName());
					// return empty map - indicates no objects loaded from
					// database
					return map;
				}

				try {
					stP = buildQuery(exprationEntry  , con);
				} catch (SQLException e) {
					// TODO Auto-generated catch block
					e.printStackTrace();
				} catch (UnusableEntryException e) {
					// TODO Auto-generated catch block
					e.printStackTrace();
				}
			}
			try {
				System.out.println("*********  loadAll -  Query Constructed:"
						+ querystr);

				ResultSet rs = stP.executeQuery();
				IGSEntry value = null;
				while (rs.next()) {
					Integer id = new Integer(rs.getInt(3));
					Person person = new Person(rs.getString(1),
							rs.getString(2), id);

					value = getConvertor().toIGSEntry(person);
					map.put(value, value);
				}
				rs.close();
				con.close();
			} catch (Exception e) {
				e.printStackTrace();
				throw new RuntimeException(e);
			}
		}

		return map;
	}
}

The buildQuery method constructs the SQL query string and fills up the JDBC PreparedStatement with appropriate values. The SQL query string includes ? for each value where the ExternalEntry extracted from the CacheQuery will include the actual values. See below example for such implementation.

private PreparedStatement buildQuery(CacheQuery query, Connection connection) throws SQLException, 
	UnusableEntryException
	{
		SQLQuery _qry = (SQLQuery)query.getQuery();
		String sql = "select * from "+ tableNames.get(_qry.getClassName())+ " where " 
		+ _qry.getQuery();
		
		System.out.println(" ********* buildQuery:" + sql);

		PreparedStatement statement = connection.prepareStatement(sql);
	
		ExternalEntry ee = null;
		ee = ((IGSEntry)query).getExternalEntry(null);
		
		Object[] fieldValues = ee.getFieldsValues();
		Object[] rangeValues = ee.getRangeValues();
		int lastpos =1;
		for( int i =0; fieldValues != null && i < fieldValues.length; i++)
		{
			if (fieldValues[i] != null)
			{
				System.out.println("Setting value into position "+ lastpos+ " Value:" 
				+ fieldValues[i]);
				statement.setObject(lastpos, fieldValues[i]);
				
				lastpos++;
			}
		}
		for(int i=0 ; rangeValues!= null && i < rangeValues.length; i++)
		{
			if (rangeValues[i] != null)
			{
				System.out.println("Setting range value position "+  lastpos+ " Value:" 
				+ rangeValues[i]);
				statement.setObject(lastpos, rangeValues[i]);
				lastpos++;
			}
		}
		return statement ;
	}

For more details, refer to the CacheLoader.load Implementation sample code above.

Reading Multiple Entry Objects

This section describes how to read multiple Entry objects using any template.

The figure illustrates how a client application reads or takes a fixed number of Entries from the space that match a given template where the actual data is loaded from a database or other external application.
The operation proceeds in two stages:

1. The client application calls the JavaSpace API readMultiple or takeMultiple methods, passing the Entry template with any attribute values (null or non-null) as first parameter.
   The client application call example:

   Entry[] persons = space.readMultiple(new person("john","doe", null), null, maxEntries);

   Where:
   maxEntries – The maximum number of objects to be read.
   The persons array should be iterated by casting each element to Person object to extract the desired data.

2. The JavaSpace API initiates data lookup in the space for a matching Entry. The first maxEntries Entries found from the Person class or its sub-classes instances that match the template are returned (note that entries under a transaction cannot be returned). If all maxEntries Entries are not found, the space tries to read them from the data source. It calls either the CacheIteratorFactory.iterator method, if implemented, or, if not implemented, it calls the CacheLoader.loadAll method, passing a CacheQuery object within a Map collection (collection with one object) that encapsulates the original template data as a parameter. The called method extracts the SQLQuery object from the CacheQuery and, using the JDBC methods, gets the remaining required record data from the database. The first required number of objects satisfying the SQLQuery are converted to an IGSEntry object and returned to the space as an array of Entry objects.The space returns the result Entry in Entry format to the client implicitly.

CacheIteratorFactory.iterator Implementation

The CacheIteratorFactory.iterator method is called by the space and has the following signature:

Iterator iterator = CacheIteratorFactory.iterator (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery by:

SQLQuery sqlQuery = CacheQuery.getQuery()

The SQL Query can now be used to retrieve the data sought using the JDBC API.

CacheLoader.loadAll Implementation

The CacheLoader Interface method load is called by the space and has the following signature:

Map persons = loadAll (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery by:

SQLQuery sqlQuery = CacheQuery.getQuery()

The SQL Query can now be used to retrieve the data sought using the JDBC API.

For the differences between Iterator and loadAll, refer to Iterator Method vs. the loadAll Method above.

Sample Code

client application: IJSpace API:

Entry[] persons = space.readMultiple(new person("john","doe", null), null, maxEntries);

Matching by SQL Query

For the IJSpace methods read (), {{take (), readMultiple (), takeMultiple () with a NO_WAIT timeout value, a SQLQuery object may be used in the first argument instead of a valued template. Using SQLQuery makes it possible to create more flexible database queries.

Two types of read operations are described.

1. Read a single Entry using an SQLQuery.
2. Read multiple Entries using an SQLQuery.

Understanding How a Query is Handled

When using the GigaSpaces JavaSpaces API with the SQLQuery or GigaSpaces JDBC API, the executed query is disassembled into smaller partial queries when delegated into the CacheLoader. The space assembles the partial results and returns them to the client.
The following two situations can occur:

Condition with OR Operation

An SQL query with multiple conditions that includes the OR operation is broken down into its different subconditions, where each subcondition is sent to the CacheStore.loadAll or CacheIteratorFactory.iterator separately.
For example, the following code:

SQLQuery person_template = new SQLQuery("person" , "firstName='john' OR age>30 OR lastName='doe'");
Entry [] result = space.readMultiple(person_template , null , 10);

will invoke the CacheIteratorFactory.iterator 3 times – each with a CacheQuery that encapsulates an SQLQuery with:

1. firstName='john'.
2. age>30.
3. lastName='doe'.

Condition with AND Operation

An SQL Query that includes conditions with the same field name using AND will not be broken down , but will invoke the CacheStore.loadAll or CacheIteratorFactory.iterator with SQLQuery that includes the condition with the AND operation, for example the code:

SQLQuery person_template = new SQLQuery("person" , "age>30 AND age<40 or lastName='doe'");
Entry [] result = space.readMultiple(person_template , null , 10);

will invoke the CacheIteratorFactory.iterator 2 times – each with a CacheQuery that will encapsulate SQLQuery with:

1. age>30 AND age<40.
2. lastName='doe'

Reading a Single Object Using SQLQuery

This section describes how to read a single Entry object using an SQLQuery.

The figure illustrates how a client application reads or takes a single Entry from the space that satisfies an SQL Query where the actual data is loaded from a database or other external application.
The operation proceeds in two stages:

1. The client application calls the JavaSpace API read or take methods, passing the SQLQuery as first parameter.
   An example for the client application call:

   Person person1 = JavaSpace.read(SQLQuery, null, NO_WAIT)

2. The JavaSpace API initiates data lookup in the space for a matching Entry. The first Entry found from the Person class or its sub-classes instances that satisfies the SQL Query is returned (note that Entries under a transaction cannot be returned). If no such Entry is found, the space calls either the CacheIteratorFactory.iterator method, if implemented, or, if not implemented, it calls the CacheLoader.loadAll method, passing a CacheQuery object within a Map collection (collection with one object) that encapsulates the original SQL Query as a parameter. The called method extracts the SQL Query object from the CacheQuery and, using the JDBC methods, gets the required record data from the database. The first object satisfying the SQLQuery is converted to an IGSEntry object and returned to the space and from the space to the client as an Entry object.

CacheIteratorFactory.iterator Implementation

The CacheIteratorFactory.iterator method is called by the space and has the following signature:

Iterator iterator = CacheIteratorFactory.iterator (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery in the following way:

SQLQuery sqlQuery = CacheQuery.getQuery()

The SQL Query can now be used to retrieve the data sought using the JDBC API.

CacheLoader.loadAll Implementation

The CacheLoader Interface method load is called by the space and has the following signature:

Map persons = loadAll (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery in the following way:

SQLQuery sqlQuery = CacheQuery.getQuery()

The SQL Query can now be used to retrieve the data sought using the JDBC API.
For the differences between using Iterator and loadAll, refer to Iterator Method vs. the loadAll Method above.

Sample Code

In client application: JavaSpaces API Using SQLQuery object:

Person person1 = (Person)space.read(SQLQuery, null, NO_WAIT);

Reading Multiple Objects Using SQLQuery

The figure above illustrates how a client application reads or takes a fixed number of multiple Entries from the space that satisfy an SQL Query where the actual data is loaded from a database or other external application.
The operation proceeds in two stages:

1. The client application calls the JavaSpace API readMultiple or takeMultiple methods, passing the SQLQuery object as first parameter.
   An example for the client application call:

   Entry[] persons = IJSpace.readMultiple(SQLQuery, null, maxEntries)

   Where:
   maxEntries – The maximum number of objects to be read.

2. The JavaSpace API initiates data lookup in the space for a matching Entry. The first maxEntries Entries found from the Person class or its sub-classes instances that satisfies the SQL Query are returned (note that Entries under a transaction cannot be returned). If all maxEntries Entries are not found, the space calls calls either the CacheIteratorFactory.iterator method, if implemented, or, if not implemented, it calls the CacheLoader.loadAll method, passing the SQLQuery object encapsulated in a CacheQuery object within a Map collection (collection with one object). The called method extracts the SQLQuery object from the CacheQuery and, using the JDBC methods, gets the remaining required record data from the database. The first required number of objects satisfying the SQLQuery are converted to an IGSEntry object and returned to the space as an array of Entry objects. The space returns the result Entry in Entry format to the client implicitly.

CacheIteratorFactory.iterator Implementation

The CacheIteratorFactory.iterator method is called by the space and has the following signature:

Iterator iterator = CacheIteratorFactory.iterator (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery in the following way:

SQLQuery sqlQuery = CacheQuery.getQuery()

CacheLoader.loadAll Implementation

The CacheLoader Interface method load is called by the space and has the following signature:

Map persons = loadAll (Map<CacheQuery>)

The SQLQuery is extracted from the CacheQuery by:

SQLQuery sqlQuery = CacheQuery.getQuery()

The SQL Query can now be used to retrieve the data sought using the JDBC API when interacting with the database.