com.pivotal.gemfirexd

Interface FabricLocator

All Superinterfaces:

FabricService

public interface FabricLocator
extends FabricService

A FabricLocator is a singleton that provides locator services in the distributed system allowing peers to discover one another. It also allows remote clients to connect to the GemFireXD cluster(distributed system) in a load-balanced manner while also providing transparent failover capability, so that the cluster appears as a single entity to a client. A FabricLocator is started by invoking the start(java.lang.String, int, java.util.Properties) method with configuration parameters as described below. Use FabricServiceManager.getFabricLocatorInstance to get a reference to the FabricLocator singleton instance.

When a program calls start(java.lang.String, int, java.util.Properties), if locators is configured then those locators provide redundancy for the locator service. This parameter must be uniform across all locators and peers in the cluster to provide consistent behaviour. All peers that are configured to use the same one of the locators in the cluster are part of the same distributed GemFireXD system.

The current version supports only a single instance of FabricLocator in a virtual machine at a time. Invoking NetworkInterface on the current virtual machine enables other programs to connect to this virtual machine using the client JDBC driver. Attempts to connect to multiple distributed systems (that is calling start(java.lang.String, int, java.util.Properties) multiple times with different configuration Properties) will result in an IllegalStateException being thrown. If start is invoked multiple times with equivalent Properties, then no action is taken during subsequent calls. Use FabricServiceManager.getFabricLocatorInstance() to access the singleton instance which can be stopped and reconnected using different Properties for different distributed system connections.

Configuration

Configuration properties are listed in the online documentation. Note that the properties that relate to data storage or exchange will have no affect since no data is hosted on locators.

Example:

    Properties p = new Properties();
    p.setProperty("conserve-sockets", "false"); // Don't conserve socket connections; Go fast
 
    final FabricLocator locator = FabricServiceManager.getFabricLocatorInstance();
    locator.start("serv1", 13000, p);
    // Start the DRDA network server and listen for client connections
    server.startNetworkServer(null,-1, null); // use defaults ; port 1527
 

Properties can be also configured in a file called 'gemfirexd.properties' or defined as system properties. GemFireXD looks for this file in the current working directory, followed by 'gemfirexd.user.home' directory and then in 'user.home' directory. The file name can be overridden using the system property -Dgemfirexd.properties=<property file>. If this value is a relative file system path then the above search is done. If it is an absolute file system path then that file must exist; no search for it is done.

The actual configuration attribute values used to connect comes from the following sources:

1. System properties. If a system property named "gemfirexd. propertyName" is defined and its value is not an empty string then its value will be used for the named configuration attribute.
2. Code properties. Otherwise if a property is defined in the bootProperties parameter object and its value is not an empty string then its value will be used for that configuration attribute.
3. File properties. Otherwise if a property is defined in a configuration property file found by this application and its value is not an empty string then its value will be used for that configuration attribute. A configuration property file may not exist. See the following section for how configuration property files are found.
4. Defaults. Otherwise a default value is used.

The primary differences between booting a distributed system using a first JDBC connection using boot properties vs. using the FabricLocator API are the following:

• Distributed Member ownership is given to the boot user when started using this API whereas boot-up using a Connection doesn't give ownership to the user. This makes a difference if SQLAuthorization is turned on. Distributed member owners have specific privileges that cannot be delegated to others like creating distributed system level users, granting / revoking privileges from other users, etc..
• By default, a network server can only be started by having network properties in the first connection in a virtual machine. What this means is that every process, whether it hosts data or not, is capable of starting up a network listening port immediately without giving applications a chance to complete their own initialization. For example, an application might want to populate certain master tables before accepting network client's requests. The start-up sequence cannot be controlled in this way when using a JDBC Connection directly, i.e. this server will be active immediately after joining the distributed system.

Nested Class Summary

Nested classes/interfaces inherited from interface com.pivotal.gemfirexd.FabricService

FabricService.State

Field Summary

Fields

Modifier and Type	Field and Description
static String	LOCATOR_DEFAULT_BIND_ADDRESS the default bind-address for locator
static int	LOCATOR_DEFAULT_PORT the default port for locator

Fields inherited from interface com.pivotal.gemfirexd.FabricService

NETSERVER_DEFAULT_PORT, STOP_NETWORK_SERVERS

Method Summary

Methods

Modifier and Type	Method and Description
void	start(String bindAddress, int port, Properties bootProperties) Start the stand-alone locator singleton instance if not already started.
void	start(String bindAddress, int port, Properties bootProperties, boolean ignoreIfStarted) Start the stand-alone locator singleton instance if not already started.
FabricService.State	status() Returns the locator status.

Methods inherited from interface com.pivotal.gemfirexd.FabricService

getAllNetworkServers, isReconnecting, startDRDAServer, startNetworkServer, startThriftServer, stop, stopAllNetworkServers, stopReconnecting, waitUntilReconnected

Field Detail

LOCATOR_DEFAULT_BIND_ADDRESS

static final String LOCATOR_DEFAULT_BIND_ADDRESS

the default bind-address for locator

See Also:

Constant Field Values

LOCATOR_DEFAULT_PORT

static final int LOCATOR_DEFAULT_PORT

the default port for locator

See Also:

Constant Field Values

Method Detail

start

void start(String bindAddress,
         int port,
         Properties bootProperties)
           throws SQLException

Start the stand-alone locator singleton instance if not already started. In case the locator has already been started then the old instance is first stopped and then started again with the new properties. Initiates and establishes connections with all the other peer members and provided locator services in the distributed system but will not host any tables or data. Clients will be able to use this node for connections if a network server ( FabricService.startNetworkServer(java.lang.String, int, java.util.Properties)) has been started on this locator. Such a client will receive server load information from the locator so that actual data connections to fabric servers will be created in a load balanced manner behind the scenes. It also allows clients to transparently failover and reconnect to another server if the current data connection to the server fails.

An GemFireXD system requiring locator services for peer discovery (as opposed to using mcast-port) needs to start at least one locator in the distributed system either as a stand-alone instance using this API, or embedded in a FabricServer by providing "start-locator" boot property to the FabricServer.start(java.util.Properties) API. For production systems it is recommended to use locator rather than mcast-port for peer discovery, and a stand-alone locator should be preferred due to lower load than an embedded one.

Apart from the properties provided to this method, they can be also configured in a file called 'gemfirexd.properties' or defined as system properties. GemFireXD looks for this file in the current working directory, followed by 'gemfirexd.user.home' directory and then in 'user.home' directory. The file name can be overridden using the system property -Dgemfirexd.properties=<property file>. If this value is a relative file system path then the above search is done. If it is an absolute file system path then that file must exist; no search for it is done.

The actual configuration attribute values used to connect comes from the following sources:

1. System properties. If a system property named "gemfirexd. propertyName" is defined and its value is not an empty string then its value will be used for the named configuration attribute.
2. Code properties. Otherwise if a property is defined in the bootProperties parameter object and its value is not an empty string then its value will be used for that configuration attribute.
3. File properties. Otherwise if a property is defined in a configuration property file found by this application and its value is not an empty string then its value will be used for that configuration attribute. A configuration property file may not exist. See the following section for how configuration property files are found.
4. Defaults. Otherwise a default value is used.

If authentication is switched on, system user credentials must also be passed to start the locator.

Parameters:

bindAddress - The host name or IP address to bind the locator port. If this is null then binds to LOCATOR_DEFAULT_BIND_ADDRESS.

port - The port to bind the locator. A value <= 0 will cause this to use the default port LOCATOR_DEFAULT_PORT.

bootProperties - Driver boot properties. If non-null, overrides default properties in 'gemfirexd.properties'.

Throws:

SQLException

start

void start(String bindAddress,
         int port,
         Properties bootProperties,
         boolean ignoreIfStarted)
           throws SQLException

Start the stand-alone locator singleton instance if not already started. Initiates and establishes connections with all the other peer members and provided locator services in the distributed system but will not host any tables or data. Clients will be able to use this node for connections if a network server ( FabricService.startNetworkServer(java.lang.String, int, java.util.Properties)) has been started on this locator. Such a client will receive server load information from the locator so that actual data connections to fabric servers will be created in a load balanced manner behind the scenes. It also allows clients to transparently failover and reconnect to another server if the current data connection to the server fails.

An GemFireXD system requiring locator services for peer discovery (as opposed to using mcast-port) needs to start at least one locator in the distributed system either as a stand-alone instance using this API, or embedded in a FabricServer by providing "start-locator" boot property to the FabricServer.start(java.util.Properties) API. For production systems it is recommended to use locator rather than mcast-port for peer discovery, and a stand-alone locator should be preferred due to lower load than an embedded one.

Apart from the properties provided to this method, they can be also configured in a file called 'gemfirexd.properties' or defined as system properties. GemFireXD looks for this file in the current working directory, followed by 'gemfirexd.user.home' directory and then in 'user.home' directory. The file name can be overridden using the system property -Dgemfirexd.properties=<property file>. If this value is a relative file system path then the above search is done. If it is an absolute file system path then that file must exist; no search for it is done.

The actual configuration attribute values used to connect comes from the following sources:

1. System properties. If a system property named "gemfirexd. propertyName" is defined and its value is not an empty string then its value will be used for the named configuration attribute.
2. Code properties. Otherwise if a property is defined in the bootProperties parameter object and its value is not an empty string then its value will be used for that configuration attribute.
3. File properties. Otherwise if a property is defined in a configuration property file found by this application and its value is not an empty string then its value will be used for that configuration attribute. A configuration property file may not exist. See the following section for how configuration property files are found.
4. Defaults. Otherwise a default value is used.

If authentication is switched on, system user credentials must also be passed to start the locator.

Parameters:

bindAddress - The host name or IP address to bind the locator port. If this is null then binds to LOCATOR_DEFAULT_BIND_ADDRESS.

port - The port to bind the locator. A value <= 0 will cause this to use the default port LOCATOR_DEFAULT_PORT.

bootProperties - Driver boot properties. If non-null, overrides default properties in 'gemfirexd.properties'.

ignoreIfStarted - if true then reuse any previous active instance, else stop any previous instance and start a new one with given properties

Throws:

SQLException

status

FabricService.State status()

Returns the locator status.

Specified by:

status in interface FabricService

Returns:

FabricService.State