com.bigdata.service
Interface IBigdataFederation<T>

Type Parameters:

T - The generic type of the client or service.

All Superinterfaces:

IFederationDelegate<T>, IIndexManager, IIndexStore

All Known Implementing Classes:

AbstractDistributedFederation, AbstractFederation, AbstractScaleOutFederation, EmbeddedFederation, JiniFederation, LocalDataServiceFederation

public interface IBigdataFederation<T>
extends IIndexManager, IFederationDelegate<T>

The client-facing interface to a bigdata federation. Note that each bigdata service has an IBigdataFederation which it uses to communicate with the other services in the federation.

Version:

$Id: IBigdataFederation.java 2265 2009-10-26 12:51:06Z thompsonbry $

Author:

Bryan Thompson

Method Summary

void	destroy() Destroys all discovered services belonging to the federation and their persistent data and disconnects from the federation.
void	dropIndex(String name) Drop a scale-out index.
IDataService	getAnyDataService() Return ANY IDataService which has been (or could be) discovered and which is part of the connected federation.
IBigdataClient<T>	getClient() Return the client object that was used to connect to the federation.
CounterSet	getCounterSet() The CounterSet which the client will use report its statistics to the ILoadBalancerService.
IDataService	getDataService(UUID serviceUUID) Resolve the service identifier to an IDataService.
IDataService	getDataServiceByName(String name) Return an IDataService joined with this IBigdataFederation and having the specified service name.
IDataService[]	getDataServices(UUID[] uuid) Return an array of IDataService references that is correlated with the given array of IDataService UUIDs.
UUID[]	getDataServiceUUIDs(int maxCount) Return an array UUIDs for IDataServices.
ExecutorService	getExecutorService() A thread pool that may be used by clients to parallelize operations against the federation.
SparseRowStore	getGlobalRowStore() Return the global SparseRowStore used to store named property sets in the federation.
CounterSet	getHostCounterSet() The node in getCounterSet() corresponding to the root of the host on which the client or service is executing.
String	getHttpdURL() The URL that may be used to access the local httpd service for this client or service.
IClientIndex	getIndex(String name, long timestamp) Obtain a view on a partitioned index.
long	getLastCommitTime() Return the last commit time for the federation (the timestamp of the most recent commit point across all IDataServices).
ILoadBalancerService	getLoadBalancerService() Return the load balancer service (or a proxy for that service).
IMetadataIndex	getMetadataIndex(String name, long timestamp) Return a read-only view of the index partitions for the named scale-out index.
IMetadataService	getMetadataService() Return the metadata service (or a proxy for the metadata service).
String	getServiceCounterPathPrefix() The path prefix under which all of the client or service's counters are located.
CounterSet	getServiceCounterSet() The node in getCounterSet() corresponding to the root of the client or service connected using this federation.
ITransactionService	getTransactionService() Return the ITransactionService (or a proxy for that service).
boolean	isDistributed() Return true iff the federation is distributed (uses RMI and is running, at least in principle, across more than one host/JVM).
boolean	isScaleOut() Return true iff the federation supports scale-out indices (supports key-range partitioned indices).
boolean	isStable() Return true iff the federation is backed by "stable" (vs transient) storage.
void	registerIndex(IndexMetadata metadata) Register a scale-out index.
UUID	registerIndex(IndexMetadata metadata, byte[][] separatorKeys, UUID[] dataServiceUUIDs) Register and statically partition a scale-out index.
UUID	registerIndex(IndexMetadata metadata, UUID dataServiceUUID) Register a scale-out index and assign the initial index partition to the specified data service.

Methods inherited from interface com.bigdata.journal.IIndexStore

getGlobalFileSystem, getResourceLocator, getResourceLockService, getTempStore

Methods inherited from interface com.bigdata.service.IFederationDelegate

didStart, getService, getServiceIface, getServiceName, getServiceUUID, isServiceReady, newHttpd, reattachDynamicCounters, serviceJoin, serviceLeave

Method Detail

getClient

IBigdataClient<T> getClient()

Return the client object that was used to connect to the federation.

Throws:

IllegalStateException - if the client disconnected and this object is no longer valid.

getHttpdURL

String getHttpdURL()

The URL that may be used to access the local httpd service for this client or service.

Returns:

The URL -or- null if the httpd service is not running.

getTransactionService

ITransactionService getTransactionService()

Return the ITransactionService (or a proxy for that service).

Returns:

The service -or- null if the service has not been discovered.

getLoadBalancerService

ILoadBalancerService getLoadBalancerService()

Return the load balancer service (or a proxy for that service).

Returns:

The service -or- null if the service has not been discovered.

getMetadataService

IMetadataService getMetadataService()

Return the metadata service (or a proxy for the metadata service).

Returns:

The service -or- null if the service has not been discovered.

getExecutorService

ExecutorService getExecutorService()

A thread pool that may be used by clients to parallelize operations against the federation. This thread pool is automatically used by the ClientIndexView.

Specified by:

getExecutorService in interface IIndexStore

getCounterSet

CounterSet getCounterSet()

The CounterSet which the client will use report its statistics to the ILoadBalancerService.

Note: Applications MAY add their own counters (within a suitable namespace) to the returned CounterSet in order to report their own performance data to the ILoadBalancerService.

See Also:

getServiceCounterSet(), getServiceCounterPathPrefix()

getHostCounterSet

CounterSet getHostCounterSet()

The node in getCounterSet() corresponding to the root of the host on which the client or service is executing.

getServiceCounterSet

CounterSet getServiceCounterSet()

The node in getCounterSet() corresponding to the root of the client or service connected using this federation.

getServiceCounterPathPrefix

String getServiceCounterPathPrefix()

The path prefix under which all of the client or service's counters are located. The returned path prefix is terminated by an ICounterSet.pathSeparator.

See Also:

getServiceCounterSet()

getDataServiceUUIDs

UUID[] getDataServiceUUIDs(int maxCount)

Return an array UUIDs for IDataServices.

Parameters:

maxCount - The maximum #of data services whose UUIDs will be returned. When zero (0) the UUID for all known data services will be returned.

Returns:

An array of UUIDs for data services.

getDataServices

IDataService[] getDataServices(UUID[] uuid)

Return an array of IDataService references that is correlated with the given array of IDataService UUIDs.

Note: This method will also resolve the UUID of an IMetadataService.

Parameters:

uuids - The (meta)data service UUIDs.

Returns:

The (meta)data service proxies.

getDataService

IDataService getDataService(UUID serviceUUID)

Resolve the service identifier to an IDataService.

Note: Whether the returned object is a proxy or the service implementation depends on whether the federation is embedded (in process) or distributed (networked).

Parameters:

serviceUUID - The identifier for a IDataService.

Returns:

The IDataService or null iff the IDataService could not be discovered from its identifier.

getAnyDataService

IDataService getAnyDataService()

Return ANY IDataService which has been (or could be) discovered and which is part of the connected federation.

Note: This method is here as a failsafe when the ILoadBalancerService is not available.

Returns:

null if there are NO known IDataServices.

getDataServiceByName

IDataService getDataServiceByName(String name)

Return an IDataService joined with this IBigdataFederation and having the specified service name. Services that are not joined will not be discovered.

Note: At least some service fabrics (such as jini) do not enforce a uniqueness constraint on the service name(s). In such cases an arbitrary IDataService method the other requirements will be returned. It is the responsibility of the administrator to ensure that each IDataService is assigned a distinct service name.

Parameters:

name - The service name.

Returns:

A service assigned that name -or- null if none is joined with the IBigdataFederation at this time.

Throws:

IllegalArgumentException - if name is null.

getMetadataIndex

IMetadataIndex getMetadataIndex(String name,
                                long timestamp)

Return a read-only view of the index partitions for the named scale-out index.

Parameters:

name - The name of the scale-out index.

Returns:

The IMetadataIndex for the named scale-out index -or- null iff there is no such scale-out index.

registerIndex

void registerIndex(IndexMetadata metadata)

Register a scale-out index.

Specified by:

registerIndex in interface IIndexManager

Parameters:

metadata - The metadata template used to create component indices for BTrees this scale-out index (this also specifies the name of the scale-out index).

TODO:

compare the throws behavior of the federation with AbstractJournal.registerIndex(IndexMetadata)

registerIndex

UUID registerIndex(IndexMetadata metadata,
                   UUID dataServiceUUID)

Register a scale-out index and assign the initial index partition to the specified data service.

Parameters:

metadata - The metadata template used to create component indices for BTrees this scale-out index (this also specifies the name of the scale-out index).

dataServiceUUID - The data service identifier (optional). When null, a data service will be selected automatically. If IndexMetadata.Options#INITIAL_DATA_SERVICE was specified, then the identified service will be used. Otherwise an underutilized service will be selected using the ILoadBalancerService.

Returns:

The UUID of the registered index.

See Also:

IndexMetadata.Options#INITIAL_DATA_SERVICE

TODO:

change to void return

registerIndex

UUID registerIndex(IndexMetadata metadata,
                   byte[][] separatorKeys,
                   UUID[] dataServiceUUIDs)

Register and statically partition a scale-out index.

Parameters:

metadata - The metadata template used to create component indices for BTrees this scale-out index (this also specifies the name of the scale-out index).

separatorKeys - The array of separator keys. Each separator key is interpreted as an unsigned byte[]. The first entry MUST be an empty byte[]. The entries MUST be in sorted order.

dataServiceUUIDs - The array of data services onto which each partition defined by a separator key will be mapped (optional). When given, the #of entries in this array MUST agree with the #of entries in the separatorKeys array and all entries must be non-null. When not given, the index partitions will be auto-assigned to the discovered data services.

Returns:

The UUID of the scale-out index.

TODO:

change to void return

dropIndex

void dropIndex(String name)

Drop a scale-out index.

Specified by:

dropIndex in interface IIndexManager

Parameters:

name - The index name.

getIndex

IClientIndex getIndex(String name,
                      long timestamp)

Obtain a view on a partitioned index.

Specified by:

getIndex in interface IIndexStore

Parameters:

name - The index name.

timestamp - A transaction identifier, ITx.UNISOLATED for the unisolated index view, ITx.READ_COMMITTED, or timestamp for a historical view no later than the specified timestamp.

Returns:

The index or null if the index does not exist.

isScaleOut

boolean isScaleOut()

Return true iff the federation supports scale-out indices (supports key-range partitioned indices). Note that a true return does NOT imply that the federation is running in a distributed environment, just that it uses the scale-out index architecture. A false return indicates that getMetadataService() WILL NOT return a IMetadataService since key-range partitioned indices are NOT supported.

See Also:

IndexMetadata

isDistributed

boolean isDistributed()

Return true iff the federation is distributed (uses RMI and is running, at least in principle, across more than one host/JVM).

isStable

boolean isStable()

Return true iff the federation is backed by "stable" (vs transient) storage. Most federation deployments are stable in this sense, but it is possible to create federation instances backed solely by transient storage and those instances will report false here. This is most typically done for testing purposes using a LocalDataServiceFederation or an EmbeddedFederation.

getGlobalRowStore

SparseRowStore getGlobalRowStore()

Return the global SparseRowStore used to store named property sets in the federation.

Specified by:

getGlobalRowStore in interface IIndexStore

See Also:

GlobalRowStoreSchema

destroy

void destroy()

Destroys all discovered services belonging to the federation and their persistent data and disconnects from the federation.

Specified by:

destroy in interface IIndexStore

getLastCommitTime

long getLastCommitTime()

Return the last commit time for the federation (the timestamp of the most recent commit point across all IDataServices).

This is useful for ITx.READ_COMMITTED operations that need to use a consistent timestamp across a series of DataServices or a series of requests against a single DataService that must use a consistent view.

Specified by:

getLastCommitTime in interface IIndexStore

Returns:

The timestamp of the most recent commit on the store or 0L iff there have been no commits.

See Also:

IRootBlockView.getLastCommitTime()