com.gpudb

Class GPUdbBase

java.lang.Object

com.gpudb.GPUdbBase

Direct Known Subclasses:

GPUdb

public abstract class GPUdbBase
extends Object

Base class for the GPUdb API that provides general functionality not specific to any particular GPUdb request. This class is never instantiated directly; its functionality is accessed via instances of the GPUdb class.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GPUdbBase.HASynchronicityMode A enumeration of high-availability synchronicity override modes.
static class	GPUdbBase.Options A set of configurable options for the GPUdb API.
static class	GPUdbBase.SubmitException An exception that occurred during the submission of a request to GPUdb.

Field Summary

Fields

Modifier and Type	Field and Description
static long	END_OF_SET Constant used with certain requests to indicate that the maximum allowed number of results should be returned.
protected static String	HA_SYNC_MODE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	GPUdbBase(List<URL> urls, GPUdbBase.Options options)
protected	GPUdbBase(String url, GPUdbBase.Options options)
protected	GPUdbBase(URL url, GPUdbBase.Options options)

Method Summary

Modifier and Type	Method and Description
<T> void	addKnownType(String typeId, Class<T> objectClass, TypeObjectMap<T> typeObjectMap) Adds a type object map for the specified class as a type descriptor for a GPUdb type, identified by a type ID, to the known type list, and also adds the type object map to the known type object map list.
void	addKnownType(String typeId, Object typeDescriptor) Adds a type descriptor for a GPUdb type (excluding types of join tables), identified by a type ID, to the known type list.
<T> void	addKnownTypeFromTable(String tableName, Class<T> objectClass, TypeObjectMap<T> typeObjectMap) Adds a type object map for the specified class as a type descriptor for the GPUdb type stored in the specified table to the known type list, and also adds the type object map to the known type object map list.
void	addKnownTypeFromTable(String tableName, Object typeDescriptor) Adds a type descriptor for the GPUdb type stored in the specified table to the known type list.
<T> void	addKnownTypeObjectMap(Class<T> objectClass, TypeObjectMap<T> typeObjectMap) Adds a type object map for the specified class to the known type object map list.
protected <T> List<T>	decode(List<String> typeIds, List<ByteBuffer> data)
protected <T> List<T>	decode(Object typeDescriptor, List<ByteBuffer> data)
protected <T> List<T>	decode(String typeId, List<ByteBuffer> data)
protected <T> List<List<T>>	decodeMultiple(List<String> typeIds, List<List<ByteBuffer>> data)
protected <T> List<List<T>>	decodeMultiple(Object typeDescriptor, List<List<ByteBuffer>> data)
protected <T> List<ByteBuffer>	encode(List<T> data)
protected <T> List<ByteBuffer>	encode(TypeObjectMap<T> typeObjectMap, List<T> data)
static String	getApiVersion() Gets the version number of the GPUdb Java API.
ExecutorService	getExecutor() Gets the executor service used for managing threads during data encoding and decoding operations.
GPUdbBase.HASynchronicityMode	getHASyncMode() Gets the current high availability synchronicity override mode.
URL	getHmURL() Gets the active URL of the GPUdb host manager.
List<URL>	getHmURLs() Gets the list of URLs for the GPUdb host manager.
Map<String,String>	getHttpHeaders() Gets the map of additional HTTP headers that will be sent to GPUdb with each request.
String	getPassword() Gets the password used for authentication to GPUdb.
int	getThreadCount() Gets the number of threads used during data encoding and decoding operations.
int	getTimeout() Gets the timeout value, in milliseconds, after which a lack of response from the GPUdb server will result in requests being aborted.
protected Object	getTypeDescriptor(String typeId)
protected <T> TypeObjectMap<T>	getTypeObjectMap(Class<T> objectClass)
URL	getURL() Gets the active URL of the GPUdb server.
List<URL>	getURLs() Gets the list of URLs for the GPUdb server.
String	getUsername() Gets the username used for authentication to GPUdb.
boolean	getUseSnappy() Gets the value of the flag indicating whether Snappy compression will be used for certain GPUdb requests that potentially submit large amounts of data.
protected HttpURLConnection	initializeHttpConnection(URL url) Create and initialize an HTTP connection object with the request headers (including authorization header), connection type, time out etc.
static <T> List<T>	list(T... values) A utility method for creating a list of objects inline.
static Map<String,String>	options(String... values) A utility method for creating a map of strings to strings} inline.
void	ping() Verifies that GPUdb is running on the server.
void	setHASyncMode(GPUdbBase.HASynchronicityMode syncMode) Sets the current high availability synchronicity override mode.
GPUdbBase	setHostManagerPort(int value) Re-sets the host manager port number for the host manager URLs.
protected void	setTypeDescriptorIfMissing(String typeId, String label, String typeSchema, Map<String,List<String>> properties)
<T extends org.apache.avro.generic.IndexedRecord> T	submitRequest(String endpoint, org.apache.avro.generic.IndexedRecord request, T response) Submits an arbitrary request to GPUdb and saves the response into a pre-created response object.
<T extends org.apache.avro.generic.IndexedRecord> T	submitRequest(String endpoint, org.apache.avro.generic.IndexedRecord request, T response, boolean enableCompression) Submits an arbitrary request to GPUdb and saves the response into a pre-created response object, optionally compressing the request before sending.
<T extends org.apache.avro.generic.IndexedRecord> T	submitRequest(URL url, org.apache.avro.generic.IndexedRecord request, T response, boolean enableCompression) Submits an arbitrary request to GPUdb via the specified URL and saves the response into a pre-created response object, optionally compressing the request before sending.
<T extends org.apache.avro.generic.IndexedRecord> T	submitRequestToHM(String endpoint, org.apache.avro.generic.IndexedRecord request, T response) Submits an arbitrary request to the GPUdb host manager and saves the response into a pre-created response object.
<T extends org.apache.avro.generic.IndexedRecord> T	submitRequestToHM(String endpoint, org.apache.avro.generic.IndexedRecord request, T response, boolean enableCompression) Submits an arbitrary request to the GPUdb host manager and saves the response into a pre-created response object, optionally compressing the request before sending.
protected void	updateHostManagerPort() Automatically resets the host manager port number for the host manager URLs by finding out what the host manager port is.

Methods inherited from class java.lang.Object

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

Field Detail

END_OF_SET

public static final long END_OF_SET

Constant used with certain requests to indicate that the maximum allowed number of results should be returned.

See Also:

Constant Field Values

HA_SYNC_MODE

protected static final String HA_SYNC_MODE

See Also:

Constant Field Values

Constructor Detail

GPUdbBase

protected GPUdbBase(String url,
                    GPUdbBase.Options options)
             throws GPUdbException

Throws:

GPUdbException

GPUdbBase

protected GPUdbBase(URL url,
                    GPUdbBase.Options options)
             throws GPUdbException

Throws:

GPUdbException

GPUdbBase

protected GPUdbBase(List<URL> urls,
                    GPUdbBase.Options options)
             throws GPUdbException

Throws:

GPUdbException

Method Detail

getApiVersion

public static String getApiVersion()

Gets the version number of the GPUdb Java API.

Returns:

the version number

list

@SafeVarargs
public static <T> List<T> list(T... values)

A utility method for creating a list of objects inline. Can be used with certain GPUdb requests for specifying lists of strings or other objects.

Type Parameters:

T - the type of objects in the list

Parameters:

values - the objects to be added to the list

Returns:

the list

options

public static Map<String,String> options(String... values)

A utility method for creating a map of strings to strings} inline. Can be used with certain GPUdb requests for specifying additional named parameters. An even number of string values must be specified; the first in each pair is the key for a map entry, and the second is the value.

Parameters:

values - an even number of string values

Returns:

the map

Throws:

IllegalArgumentException - if an odd number of values is specified

getURLs

public List<URL> getURLs()

Gets the list of URLs for the GPUdb server. At any given time, one URL will be active and used for all GPUdb calls (call getURL to determine which one), but in the event of failure, the other URLs will be tried in order, and if a working one is found it will become the new active URL.

Returns:

the list of URLs

getURL

public URL getURL()

Gets the active URL of the GPUdb server.

Returns:

the URL

getHmURLs

public List<URL> getHmURLs()

Gets the list of URLs for the GPUdb host manager. At any given time, one URL will be active and used for all GPUdb calls (call getHmURL to determine which one), but in the event of failure, the other URLs will be tried in order, and if a working one is found it will become the new active URL.

Returns:

the list of URLs

getHmURL

public URL getHmURL()

Gets the active URL of the GPUdb host manager.

Returns:

the URL

getHASyncMode

public GPUdbBase.HASynchronicityMode getHASyncMode()

Gets the current high availability synchronicity override mode.

Returns:

the ha synchronicity override mode

See Also:

setHASyncMode(HASynchronicityMode)

getUsername

public String getUsername()

Gets the username used for authentication to GPUdb. Will be an empty string if none was provided to the GPUdb constructor via GPUdbBase.Options.

Returns:

the username

See Also:

GPUdbBase.Options.setUsername(String)

getPassword

public String getPassword()

Gets the password used for authentication to GPUdb. Will be an empty string if none was provided to the GPUdb constructor via GPUdbBase.Options.

Returns:

the password

See Also:

GPUdbBase.Options.setPassword(String)

getUseSnappy

public boolean getUseSnappy()

Gets the value of the flag indicating whether Snappy compression will be used for certain GPUdb requests that potentially submit large amounts of data. Will be false if not overridden using the GPUdb constructor via GPUdbBase.Options.

Returns:

the value of the Snappy compression flag

See Also:

GPUdbBase.Options.setUseSnappy(boolean)

getThreadCount

public int getThreadCount()

Gets the number of threads used during data encoding and decoding operations. Will be one if not overridden using the GPUdb constructor via GPUdbBase.Options.

Returns:

the number of threads

See Also:

GPUdbBase.Options.setThreadCount(int)

getExecutor

public ExecutorService getExecutor()

Gets the executor service used for managing threads during data encoding and decoding operations. Will be null if none was provided to the GPUdb constructor via GPUdbBase.Options.

Returns:

the executor service

See Also:

GPUdbBase.Options.setExecutor(ExecutorService)

getHttpHeaders

public Map<String,String> getHttpHeaders()

Gets the map of additional HTTP headers that will be sent to GPUdb with each request. Will be empty if none were provided to the GPUdb constructor via GPUdbBase.Options.

Returns:

the map

See Also:

GPUdbBase.Options.addHttpHeader(String, String), GPUdbBase.Options.setHttpHeaders(Map)

getTimeout

public int getTimeout()

Gets the timeout value, in milliseconds, after which a lack of response from the GPUdb server will result in requests being aborted. A timeout of zero is interpreted as an infinite timeout. Note that this applies independently to various stages of communication, so overall a request may run for longer than this without being aborted.

Returns:

the timeout value

See Also:

GPUdbBase.Options.setTimeout(int)

setHASyncMode

public void setHASyncMode(GPUdbBase.HASynchronicityMode syncMode)

Sets the current high availability synchronicity override mode. Until it is changed, all subsequent endpoint calls made to the server will maintain the given synchronicity across all clusters in the high availability ring. When set to GPUdbBase.HASynchronicityMode.DEFAULT, normal operation will resume (where the high availability process determines which endpoints will be synchronous and which ones will be asynchronous).

Parameters:

syncMode - the ha synchronicity override mode

setHostManagerPort

public GPUdbBase setHostManagerPort(int value)
                             throws IllegalArgumentException,
                                    GPUdbException

Re-sets the host manager port number for the host manager URLs. Some endpoints are supported only at the host manager, rather than the head node of the database.

Parameters:

value - the host manager port number

Returns:

the current GPUdbBase instance

Throws:

IllegalArgumentException

GPUdbException

updateHostManagerPort

protected void updateHostManagerPort()
                              throws GPUdbException

Automatically resets the host manager port number for the host manager URLs by finding out what the host manager port is.

Throws:

GPUdbException

addKnownType

public void addKnownType(String typeId,
                         Object typeDescriptor)

Adds a type descriptor for a GPUdb type (excluding types of join tables), identified by a type ID, to the known type list. If that type is subsequently encountered in results from a GPUdb request for which an explicit type descriptor is not provided, the specified type descriptor will be used for decoding.

Parameters:

typeId - the type ID of the type in GPUdb (must not be the type of a join table)

typeDescriptor - the type descriptor to be used for decoding the type

Throws:

IllegalArgumentException - if typeDescriptor is not a Schema, Type, TypeObjectMap, or Class that implements IndexedRecord

addKnownType

public <T> void addKnownType(String typeId,
                             Class<T> objectClass,
                             TypeObjectMap<T> typeObjectMap)

Adds a type object map for the specified class as a type descriptor for a GPUdb type, identified by a type ID, to the known type list, and also adds the type object map to the known type object map list. If either the type or the specified class is subsequently encountered in a GPUdb request for which an explicit type object map is not provided, or in its results, the specified type object map will be used for decoding and encoding.

Type Parameters:

T - the class

Parameters:

typeId - the type ID of the type in GPUdb

objectClass - the class

typeObjectMap - the type object map to be used for encoding and decoding

addKnownTypeFromTable

public void addKnownTypeFromTable(String tableName,
                                  Object typeDescriptor)
                           throws GPUdbException

Adds a type descriptor for the GPUdb type stored in the specified table to the known type list. If that type is subsequently encountered in results from a GPUdb request for which an explicit type descriptor is not provided, the specified type descriptor will be used for decoding. Note that this method makes a request to GPUdb to obtain table information.

Parameters:

tableName - the name of the table in GPUdb

typeDescriptor - the type descriptor to be used for decoding the type

Throws:

IllegalArgumentException - if typeDescriptor is not a Schema, Type, TypeObjectMap, or Class that implements IndexedRecord

GPUdbException - if the table does not exist or is not homogeneous, or if an error occurs during the request for table information

addKnownTypeFromTable

public <T> void addKnownTypeFromTable(String tableName,
                                      Class<T> objectClass,
                                      TypeObjectMap<T> typeObjectMap)
                               throws GPUdbException

Adds a type object map for the specified class as a type descriptor for the GPUdb type stored in the specified table to the known type list, and also adds the type object map to the known type object map list. If either the type or the specified class is subsequently encountered in a GPUdb request for which an explicit type object map is not provided, or in its results, the specified type object map will be used for decoding and encoding. Note that this method makes a request to GPUdb to obtain table information.

Type Parameters:

T - the class

Parameters:

tableName - the name of the table in GPUdb

objectClass - the class

typeObjectMap - the type object map to be used for encoding and decoding

Throws:

GPUdbException - if the table does not exist or is not homogeneous, or if an error occurs during the request for information

addKnownTypeObjectMap

public <T> void addKnownTypeObjectMap(Class<T> objectClass,
                                      TypeObjectMap<T> typeObjectMap)

Adds a type object map for the specified class to the known type object map list. If that class is subsequently encountered in a GPUdb request for which an explicit type object map is not provided, the specified type object map will be used for encoding.

Type Parameters:

T - the class

Parameters:

objectClass - the class

typeObjectMap - the type object map to be used for encoding

decode

protected <T> List<T> decode(Object typeDescriptor,
                             List<ByteBuffer> data)
                      throws GPUdbException

Throws:

GPUdbException

decode

protected <T> List<T> decode(String typeId,
                             List<ByteBuffer> data)
                      throws GPUdbException

Throws:

GPUdbException

decode

protected <T> List<T> decode(List<String> typeIds,
                             List<ByteBuffer> data)
                      throws GPUdbException

Throws:

GPUdbException

decodeMultiple

protected <T> List<List<T>> decodeMultiple(Object typeDescriptor,
                                           List<List<ByteBuffer>> data)
                                    throws GPUdbException

Throws:

GPUdbException

decodeMultiple

protected <T> List<List<T>> decodeMultiple(List<String> typeIds,
                                           List<List<ByteBuffer>> data)
                                    throws GPUdbException

Throws:

GPUdbException

encode

protected <T> List<ByteBuffer> encode(List<T> data)
                               throws GPUdbException

Throws:

GPUdbException

encode

protected <T> List<ByteBuffer> encode(TypeObjectMap<T> typeObjectMap,
                                      List<T> data)
                               throws GPUdbException

Throws:

GPUdbException

getTypeDescriptor

protected Object getTypeDescriptor(String typeId)
                            throws GPUdbException

Throws:

GPUdbException

getTypeObjectMap

protected <T> TypeObjectMap<T> getTypeObjectMap(Class<T> objectClass)
                                         throws GPUdbException

Throws:

GPUdbException

setTypeDescriptorIfMissing

protected void setTypeDescriptorIfMissing(String typeId,
                                          String label,
                                          String typeSchema,
                                          Map<String,List<String>> properties)
                                   throws GPUdbException

Throws:

GPUdbException

initializeHttpConnection

protected HttpURLConnection initializeHttpConnection(URL url)
                                              throws Exception

Create and initialize an HTTP connection object with the request headers (including authorization header), connection type, time out etc.

Parameters:

url - the URL to which the connection needs to be made

Returns:

the initialized HTTP connection object

Throws:

Exception

submitRequest

public <T extends org.apache.avro.generic.IndexedRecord> T submitRequest(String endpoint,
                                                                         org.apache.avro.generic.IndexedRecord request,
                                                                         T response)
                                                                  throws GPUdbBase.SubmitException

Submits an arbitrary request to GPUdb and saves the response into a pre-created response object. The request and response objects must implement the Avro IndexedRecord interface.

Type Parameters:

T - the type of the response object

Parameters:

endpoint - the GPUdb endpoint to send the request to

request - the request object

response - the response object

Returns:

the response object (same as response parameter)

Throws:

GPUdbBase.SubmitException - if an error occurs while submitting the request

submitRequest

public <T extends org.apache.avro.generic.IndexedRecord> T submitRequest(String endpoint,
                                                                         org.apache.avro.generic.IndexedRecord request,
                                                                         T response,
                                                                         boolean enableCompression)
                                                                  throws GPUdbBase.SubmitException

Submits an arbitrary request to GPUdb and saves the response into a pre-created response object, optionally compressing the request before sending. The request and response objects must implement the Avro IndexedRecord interface. The request will only be compressed if enableCompression is true and the GPUdb constructor was called with the Snappy compression flag set to true.

Type Parameters:

T - the type of the response object

Parameters:

endpoint - the GPUdb endpoint to send the request to

request - the request object

response - the response object

enableCompression - whether to compress the request

Returns:

the response object (same as response parameter)

Throws:

GPUdbBase.SubmitException - if an error occurs while submitting the request

submitRequestToHM

public <T extends org.apache.avro.generic.IndexedRecord> T submitRequestToHM(String endpoint,
                                                                             org.apache.avro.generic.IndexedRecord request,
                                                                             T response)
                                                                      throws GPUdbBase.SubmitException

Submits an arbitrary request to the GPUdb host manager and saves the response into a pre-created response object. The request and response objects must implement the Avro IndexedRecord interface.

Type Parameters:

T - the type of the response object

Parameters:

endpoint - the GPUdb endpoint to send the request to

request - the request object

response - the response object

Returns:

the response object (same as response parameter)

Throws:

GPUdbBase.SubmitException - if an error occurs while submitting the request

submitRequestToHM

public <T extends org.apache.avro.generic.IndexedRecord> T submitRequestToHM(String endpoint,
                                                                             org.apache.avro.generic.IndexedRecord request,
                                                                             T response,
                                                                             boolean enableCompression)
                                                                      throws GPUdbBase.SubmitException

Submits an arbitrary request to the GPUdb host manager and saves the response into a pre-created response object, optionally compressing the request before sending. The request and response objects must implement the Avro IndexedRecord interface. The request will only be compressed if enableCompression is true and the GPUdb constructor was called with the Snappy compression flag set to true.

Type Parameters:

T - the type of the response object

Parameters:

endpoint - the GPUdb endpoint to send the request to

request - the request object

response - the response object

enableCompression - whether to compress the request

Returns:

the response object (same as response parameter)

Throws:

GPUdbBase.SubmitException - if an error occurs while submitting the request

submitRequest

public <T extends org.apache.avro.generic.IndexedRecord> T submitRequest(URL url,
                                                                         org.apache.avro.generic.IndexedRecord request,
                                                                         T response,
                                                                         boolean enableCompression)
                                                                  throws GPUdbBase.SubmitException

Submits an arbitrary request to GPUdb via the specified URL and saves the response into a pre-created response object, optionally compressing the request before sending. The request and response objects must implement the Avro IndexedRecord interface. The request will only be compressed if enableCompression is true and the GPUdb constructor was called with the Snappy compression flag set to true.

Type Parameters:

T - the type of the response object

Parameters:

url - the URL to send the request to

request - the request object

response - the response object

enableCompression - whether to compress the request

Returns:

the response object (same as response parameter)

Throws:

GPUdbBase.SubmitException - if an error occurs while submitting the request

ping

public void ping()
          throws GPUdbException

Verifies that GPUdb is running on the server.

Throws:

GPUdbException - if an error occurs and/or GPUdb is not running on the server