Package com.gpudb

Class RecordRetriever<T>

java.lang.Object

com.gpudb.RecordRetriever<T>

Type Parameters:

T - the type of object being retrieved

public class RecordRetriever<T>
extends Object

Object that permits efficient retrieval of records from GPUdb, with support for multi-head access. RecordRetriever instances are thread safe and may be used from any number of threads simultaneously.

Constructor Summary

Constructors

Constructor	Description
RecordRetriever(GPUdb gpudb, String tableName, Type type)	Creates a RecordRetriever with the specified parameters.
RecordRetriever(GPUdb gpudb, String tableName, TypeObjectMap<T> typeObjectMap)	Creates a RecordRetriever with the specified parameters.
RecordRetriever(GPUdb gpudb, String tableName, TypeObjectMap<T> typeObjectMap, WorkerList workers)	Creates a RecordRetriever with the specified parameters.
RecordRetriever(GPUdb gpudb, String tableName, TypeObjectMap<T> typeObjectMap, WorkerList workers, Map<String,String> options)	Creates a RecordRetriever with the specified parameters.
RecordRetriever(GPUdb gpudb, String tableName, TypeObjectMap<T> typeObjectMap, Map<String,String> options)	Creates a RecordRetriever with the specified parameters.
RecordRetriever(GPUdb gpudb, String tableName, Type type, WorkerList workers)	Creates a RecordRetriever with the specified parameters.
RecordRetriever(GPUdb gpudb, String tableName, Type type, WorkerList workers, Map<String,String> options)	Creates a RecordRetriever with the specified parameters.
RecordRetriever(GPUdb gpudb, String tableName, Type type, Map<String,String> options)	Creates a RecordRetriever with the specified parameters.

Method Summary

Modifier and Type	Method	Description
GetRecordsResponse<T>	getByKey(List<Object> keyValues, String expression)	Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not.
GetRecordsResponse<T>	getByKey(List<Object> keyValues, String expression, long offset)	Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not.
GetRecordsByColumnResponse	getColumnsByKey(List<String> columns, List<Object> keyValues, String expression)	Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not.
GetRecordsByColumnResponse	getColumnsByKey(List<String> columns, List<Object> keyValues, String expression, long offset)	Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not.
GPUdb	getGPUdb()	Gets the GPUdb instance from which records will be retrieved.
Map<String,String>	getOptions()	Gets the options currently used for the retriever methods.
String	getTableName()	Gets the name of the table from which records will be retrieved.
boolean	isDoingWorkerLookup()
boolean	isUsingHeadRank()
RecordRetriever<T>	setOptions(Map<String,String> options)	Sets the options to be used for the retriever methods.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       Type type)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.
It will use default settings for the GPUdb.getRecords(String, long, long, Map) call supporting getByKey(List, String) and the GPUdb.getRecordsByColumn(String, List, long, long, Map) call supporting getColumnsByKey(List, List, String).
Details can be found at GetRecordsRequest.Options and GetRecordsByColumnRequest.Options, respectively.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

type - the Type of records being retrieved

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       Type type,
                       Map<String,String> options)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

type - the Type of records being retrieved

options - optional parameters to pass to GPUdb while retrieving (null for no parameters)
This is the same set of options as accepted by the GPUdb.getRecords(String, long, long, Map) and GPUdb.getRecordsByColumn(String, List, long, long, Map) calls.
The details can be found at GetRecordsRequest.Options and GetRecordsByColumnRequest.Options.

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       Type type,
                       WorkerList workers)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

type - the Type of records being retrieved

workers - worker list for multi-head retrieval (null to disable multi-head retrieval)

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       Type type,
                       WorkerList workers,
                       Map<String,String> options)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

type - the Type of records being retrieved

workers - worker list for multi-head retrieval (null to disable multi-head retrieval)

options - optional parameters to pass to GPUdb while retrieving (null for no parameters)
This is the same set of options as accepted by the GPUdb.getRecords(String, long, long, Map) and GPUdb.getRecordsByColumn(String, List, long, long, Map) calls.
The details can be found at GetRecordsRequest.Options and GetRecordsByColumnRequest.Options.

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       TypeObjectMap<T> typeObjectMap)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

typeObjectMap - the TypeObjectMap for the type of records being retrieved

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       TypeObjectMap<T> typeObjectMap,
                       Map<String,String> options)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

typeObjectMap - the TypeObjectMap for the type of records being retrieved

options - optional parameters to pass to GPUdb while retrieving (null for no parameters)
This is the same set of options as accepted by the GPUdb.getRecords(String, long, long, Map) and GPUdb.getRecordsByColumn(String, List, long, long, Map) calls.
The details can be found at GetRecordsRequest.Options and GetRecordsByColumnRequest.Options.

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       TypeObjectMap<T> typeObjectMap,
                       WorkerList workers)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

typeObjectMap - the TypeObjectMap for the type of records being retrieved

workers - worker list for multi-head retrieval (null to disable multi-head retrieval)

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

RecordRetriever

public RecordRetriever(GPUdb gpudb,
                       String tableName,
                       TypeObjectMap<T> typeObjectMap,
                       WorkerList workers,
                       Map<String,String> options)
                throws GPUdbException

Creates a RecordRetriever with the specified parameters.

Parameters:

gpudb - the GPUdb instance to retrieve records from

tableName - the table to retrieve records from

typeObjectMap - the TypeObjectMap for the type of records being retrieved

workers - worker list for multi-head retrieval (null to disable multi-head retrieval)

options - optional parameters to pass to GPUdb while retrieving (null for no parameters)
This is the same set of options as accepted by the GPUdb.getRecords(String, long, long, Map) and GPUdb.getRecordsByColumn(String, List, long, long, Map) calls.
The details can be found at GetRecordsRequest.Options and GetRecordsByColumnRequest.Options.

Throws:

GPUdbException - if a configuration error occurs

IllegalArgumentException - if an invalid parameter is specified

Method Detail

getGPUdb

public GPUdb getGPUdb()

Gets the GPUdb instance from which records will be retrieved.

Returns:

the GPUdb instance from which records will be retrieved

getTableName

public String getTableName()

Gets the name of the table from which records will be retrieved.

Returns:

the name of the table from which records will be retrieved

isUsingHeadRank

public boolean isUsingHeadRank()

Returns:

whether this RecordRetriever object is using the head-rank to do a simple record fetching (not utilizing the server's key lookup feature) (true value), or using multi-head (the worker ranks) for key lookup (false value).

isDoingWorkerLookup

public boolean isDoingWorkerLookup()

Returns:

whether this RecordRetriever object is using the worker ranks to do key lookups (true value), or doing simple record fetching (not the server's key lookup feature) (false value). Note that this will not reflect the non-worker lookup scenario where only an expression is supplied and the table is sharded.

getOptions

public Map<String,String> getOptions()

Gets the options currently used for the retriever methods. Note that any GetRecordsRequest.Options.EXPRESSION options will get overridden at the next getByKey(java.util.List<java.lang.Object>, java.lang.String) call with the appropriate expression.

Returns:

the options used during record retrieval

See Also:

setOptions(java.util.Map<java.lang.String, java.lang.String>)

setOptions

public RecordRetriever<T> setOptions(Map<String,String> options)

Sets the options to be used for the retriever methods.

Parameters:

options - the options to be used during record retrieval

Returns:

the current RecordRetriever instance

See Also:

GetRecordsRequest.Options.EXPRESSION

getByKey

public GetRecordsResponse<T> getByKey(List<Object> keyValues,
                                      String expression)
                               throws GPUdbException

Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not.
This method operates in four modes, depending on the parameters passed:

• keyValues only - attempts a direct-to-rank lookup for records matching the given key values
• keyValues and expression - attempts a direct-to-rank lookup for records matching the given key values, filtering them by the given expression
• expression only - requests, via the head rank, all records in the table matching the given filter expression
• neither - retrieves all records from the table via the head rank

Parameters:

keyValues - the key values to use for the lookup; these must correspond to either the explicit or implicit shard key for sharded tables or the primary key of replicated tables

expression - a filter expression that will be applied to the data requested by the key values; if no key values are specified this filter will be applied to all of the data in the target table

Returns:

a GetRecordsResponse with the requested records

Throws:

GPUdbException

getByKey

public GetRecordsResponse<T> getByKey(List<Object> keyValues,
                                      String expression,
                                      long offset)
                               throws GPUdbException

Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not. Returns records in the overall result set starting from the given offset.
This method operates in four modes, depending on the parameters passed:

• keyValues only - attempts a direct-to-rank lookup for records matching the given key values
• keyValues and expression - attempts a direct-to-rank lookup for records matching the given key values, filtering them by the given expression
• expression only - requests, via the head rank, all records in the table matching the given filter expression
• neither - retrieves all records from the table via the head rank

Parameters:

keyValues - the key values to use for the lookup; these must correspond to either the explicit or implicit shard key for sharded tables or the primary key of replicated tables

expression - a filter expression that will be applied to the data requested by the key values; if no key values are specified this filter will be applied to all of the data in the target table

offset - offset of the record(s) within the result set to return

Returns:

a GetRecordsResponse with the requested records

Throws:

GPUdbException

getColumnsByKey

public GetRecordsByColumnResponse getColumnsByKey(List<String> columns,
                                                  List<Object> keyValues,
                                                  String expression)
                                           throws GPUdbException

Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not.
This method operates in four modes, depending on the parameters passed:

• keyValues only - attempts a direct-to-rank lookup for records matching the given key values
• keyValues and expression - attempts a direct-to-rank lookup for records matching the given key values, filtering them by the given expression
• expression only - requests, via the head rank, all records in the table matching the given filter expression
• neither - retrieves all records from the table via the head rank

Parameters:

columns - The requested columns (which can include expressions) being requested. May use "*" for all columns.

keyValues - the key values to use for the lookup; these must correspond to either the explicit or implicit shard key for sharded tables or the primary key of replicated tables

expression - a filter expression that will be applied to the data requested by the key values; if no key values are specified this filter will be applied to all of the data in the target table

Returns:

a GetRecordsResponse with the requested records

Throws:

GPUdbException

getColumnsByKey

public GetRecordsByColumnResponse getColumnsByKey(List<String> columns,
                                                  List<Object> keyValues,
                                                  String expression,
                                                  long offset)
                                           throws GPUdbException

Retrieves records with the given key values and filter expression from the database using a direct-to-rank fast key lookup, if possible, and falling back to a standard lookup via the head node, if not. Returns records in the overall result set starting from the given offset.
This method operates in four modes, depending on the parameters passed:

• keyValues only - attempts a direct-to-rank lookup for records matching the given key values
• keyValues and expression - attempts a direct-to-rank lookup for records matching the given key values, filtering them by the given expression
• expression only - requests, via the head rank, all records in the table matching the given filter expression
• neither - retrieves all records from the table via the head rank

Parameters:

columns - The requested columns (which can include expressions) being requested. May use "*" for all columns.

keyValues - the key values to use for the lookup; these must correspond to either the explicit or implicit shard key for sharded tables or the primary key of replicated tables

expression - a filter expression that will be applied to the data requested by the key values; if no key values are specified this filter will be applied to all of the data in the target table

offset - offset of the record(s) within the result set to return

Returns:

a GetRecordsResponse with the requested records

Throws:

GPUdbException