com.bigdata.service

Interface IBigdataClient<T>

Type Parameters:

T - The generic type of the client or service.

All Known Implementing Classes:

AbstractClient, AbstractScaleOutClient, EmbeddedClient

public interface IBigdataClient<T>

Interface for clients of a IBigdataFederation.

An application uses a IBigdataClient to connect to an IBigdataFederation. Once connected, the application uses the IBigdataFederation for operations against a given federation.

An application can read and write on multiple federations by creating an IBigdataClient for each federation to which it needs to establish a connection. In this manner, an application can connect to federations that are deployed using different service discovery frameworks. However, precisely how the client is configured to identify the federation depends on the specific service discovery framework, including any protocol options or security measures, with which that federation was deployed. Likewise, the services within a given federation only see those services which belong to that federation. Therefore federation to federation data transfers MUST go through a client.

Applications normally work with scale-out indices using the methods defined by IBigdataFederation to register, drop, or access indices.

An application may use an ITransactionManagerService if needs to use transactions as opposed to unisolated reads and writes. When the client requests a transaction, the transaction manager responds with a long integer containing the transaction identifier - this is simply the unique start time assigned to that transaction by the transaction manager. The client then provides that transaction identifier for operations that are isolated within the transaction. When the client is done with the transaction, it must use the transaction manager to either abort or commit the transaction. (Transactions that fail to progress may be eventually aborted.)

When using unisolated operations, the client simply specifies ITx.UNISOLATED as the timestamp for its operations.

Version:

$Id$

Author:

Bryan Thompson

See Also:

ClientIndexView

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IBigdataClient.Options Configuration options for IBigdataClients.

Method Summary

Methods

Modifier and Type	Method and Description
IBigdataFederation<T>	connect() Connect to a bigdata federation.
void	disconnect(boolean immediateShutdown) Disconnect from the bigdata federation.
boolean	getBatchApiOnly() When true requests for non-batch API operations will throw exceptions.
int	getDefaultRangeQueryCapacity() The default capacity when a client issues a range query request.
IBigdataFederation<T>	getFederation() Return the connected federation,
int	getIndexCacheCapacity() The capacity of the client's IIndex proxy cache.
long	getIndexCacheTimeout() The timeout in milliseconds for stale entries in the client's IIndex proxy cache.
int	getMaxParallelTasksPerRequest() The maximum #of tasks that may be submitted in parallel for a single user request.
int	getMaxStaleLocatorRetries() The maximum #of retries when an operation results in a StaleLocatorException.
Properties	getProperties() An object wrapping the properties used to configure the client.
long	getTaskTimeout() The timeout in milliseconds for a task submitted to an IDataService.
int	getThreadPoolSize() The configured #of threads in the client's thread pool.
boolean	isConnected() Return true iff the client is connected to a federation.
boolean	isReadConsistent()

Method Detail

connect

IBigdataFederation<T> connect()

Connect to a bigdata federation. If the client is already connected, then the existing connection is returned.

Returns:

The object used to access the federation services.

Throws:

RuntimeException - if the connection can not be established.

getFederation

IBigdataFederation<T> getFederation()

Return the connected federation,

Throws:

IllegalStateException - if the client is not connected.

disconnect

void disconnect(boolean immediateShutdown)

Disconnect from the bigdata federation.

Normal shutdown allows any existing client requests to federation services to complete but does not schedule new requests, and then terminates any background processing that is being performed on the behalf of the client (service discovery, etc).

Immediate shutdown terminates any client requests to federation services, and then terminate any background processing that is being performed on the behalf of the client (service discovery, etc).

Note: Immediate shutdown can cause odd exceptions to be logged. Normal shutdown is recommended unless there is a reason to force immediate shutdown.

Parameters:

immediateShutdown - When true an immediate shutdown will be performed as described above. Otherwise a normal shutdown will be performed.

isConnected

boolean isConnected()

Return true iff the client is connected to a federation.

getThreadPoolSize

int getThreadPoolSize()

The configured #of threads in the client's thread pool.

See Also:

IBigdataClient.Options.CLIENT_THREAD_POOL_SIZE

getDefaultRangeQueryCapacity

int getDefaultRangeQueryCapacity()

The default capacity when a client issues a range query request.

See Also:

IBigdataClient.Options.CLIENT_RANGE_QUERY_CAPACITY

getBatchApiOnly

boolean getBatchApiOnly()

When true requests for non-batch API operations will throw exceptions.

See Also:

IBigdataClient.Options.CLIENT_BATCH_API_ONLY

getMaxStaleLocatorRetries

int getMaxStaleLocatorRetries()

The maximum #of retries when an operation results in a StaleLocatorException.

See Also:

IBigdataClient.Options.CLIENT_MAX_STALE_LOCATOR_RETRIES

getMaxParallelTasksPerRequest

int getMaxParallelTasksPerRequest()

The maximum #of tasks that may be submitted in parallel for a single user request.

See Also:

IBigdataClient.Options.CLIENT_MAX_PARALLEL_TASKS_PER_REQUEST

isReadConsistent

boolean isReadConsistent()

See Also:

IBigdataClient.Options.CLIENT_READ_CONSISTENT

getTaskTimeout

long getTaskTimeout()

The timeout in milliseconds for a task submitted to an IDataService.

See Also:

IBigdataClient.Options.CLIENT_TASK_TIMEOUT

getIndexCacheCapacity

int getIndexCacheCapacity()

The capacity of the client's IIndex proxy cache.

See Also:

IBigdataClient.Options.CLIENT_INDEX_CACHE_CAPACITY

getIndexCacheTimeout

long getIndexCacheTimeout()

The timeout in milliseconds for stale entries in the client's IIndex proxy cache.

See Also:

IBigdataClient.Options.CLIENT_INDEX_CACHE_TIMEOUT

getProperties

Properties getProperties()

An object wrapping the properties used to configure the client.