Pivotal.Data.GemFireXD.GFXDClientConnection

Pivotal.Data.GemFireXD.GFXDClientConnection establishes connections to GemFire XD locators or servers using the Network client driver.

It provides the same functionality as the JDBC URL scheme 'jdbc:gemfirexd://'. This class implements ADO.NET's System.Data.IDbConnection interface and extends the abstract System.Data.Common.DbConnection class. It has GFXDConnection class as its abstract base that will be used for other GemFire XD connection types that may be provided in future.

By default the Pivotal.Data.GemFireXD.GFXDClientConnection class and underlying driver maintain a pool of connections to avoid the overhead of repeatedly establishing the same connection over and over again. Any connection strings that match exactly (including the specification of connection pool properties) are assigned and managed from the same connection pool. If a new connection is created that does not match a previously-created connection, then GemFire XD creates a new pool for that connection, and subsequent requests with the same string may be allocated from the pool. You can use connection properties to change the default behavior of GemFire XD connection pooling. See About Connection Pooling for more information.

Constructors

Method Description
GFXDClientConnection() Returns a new default connection object with no associated connection string. A connection string must be specified for this connection object to be useful before invocation of Open method.
GFXDClientConnection(string connectionString) Returns a new connection object with the specified connection string. The connection string must follow the same rules as described for the GFXDConnectionString property.

GemFire XD-Specific Extensions

The sections that follow describe GemFire XD specific extensions. The MSDN documentation of IDbConnection and DbConnection describe the other API methods.

ConnectionString

The ConnectionString is required to be of the form: Server=<host>:<port>[;<key>=<value>]. The semi-colon separated key, value pairs are optional and can be one of those as described below in section Open(Dictionary<string, object>). This can be provided in the constructor of GFXDClientConnection or set in the ConnectionString property.

AutoCommit

This property can be used to get or set auto-commit property for all subsequent transactional operations executed on this connection. If set to true then it causes an implicit commit to be invoked at the end of every statement execution in a transaction.

BeginGFXDTransaction

Overloaded methods to start a new GemFire XD transaction without creating a GFXDTransaction object. The transaction can be controlled using the Commit or Rollback methods directly on the connection. The zero argument method will start a new transaction with isolation-level System.Data.IsolationLevel.Unspecified that maps to System.Data.IsolationLevel.ReadCommitted.

Commit

Commit the active transaction in progress on this connection. There is no support for nested transactions in GemFire XD so at most one transaction can be in progress at a given time on a connection.

IsolationLevel

Property to get the isolation level for the current transaction, if any. If no transaction is in progress then this returns System.Data.IsolationLevel.Unspecified.

Open(Dictionary<string, object>)

Open the connection providing an optional set of properties. This set of properties can also be provided as part of the connection string as semi-colon separated <key>=<value> pairs..The available properties are:
  • load-balance: (Boolean) Indicates whether to attempt load-balancing for this connection by selecting a less loaded server for actual connection. Load balancing for clients works only if there is a locator in the GemFire XD cluster, and clients should preferably use the locator for creating the connection. Default is true. Note that when load balancing is enabled, clients may not be able to connect to a specific server even if they provide that server's unique port number for client connections.
  • disable-streaming: (Boolean) If set to false then queries executed on the GemFire XD servers will stream results as soon as some members have data. If set to true then streaming will be disabled and the query result will not be sent back till all servers in the cluster have completely sent back their results. If set to false then this has implications in the way failover works when servers fail – if a server happens to fail while some result has already been consumed by the client using a GFXDDataReader then the driver cannot transparently failover to the new server rather the client will receive a GFXDException with State "X0Z01". Default is false.
  • user: (String) The user name to be used for this connection if authentication is enabled on the servers.
  • password: (String) The password to be used for this connection if authentication is enabled on the servers.
  • Maximum Pool Size: (Integer) The maximum number of connections maintained in the connection pool. Default is 100.
  • Connection Timeout: (Integer) The maximum number of seconds that a thread will wait to obtain a connection from the connection pool. After this time expires, the thread receives an "All connections are used" exception. Default is 15.
  • Connection Lifetime: (Integer) The maximum length of time in seconds that a connection in the pool can remain idle. The driver automatically terminates idle connections from the pool. Default is 180.

Rollback

Rollback the active transaction in progress on this connection. There is no support for nested transactions in GemFire XD so at most one transaction can be in progress at a given time on a connection.

Example: Connect to a single server with defaults and disable-streaming property

// Start a GemFire XD server that starts a network server on localhost:1527
$ gfxd server start
Starting GemFire XD Server using multicast for peer discovery: 239.192.81.1[10334]
Starting network server for GemFire XD Server at address localhost/127.0.0.1[1527]
...

// Open a new connection to the network server running on localhost:1527
string host = "localhost";
int port = 1527;
string connectionStr = string.Format("server={0}:{1}", host, port);
using (GFXDClientConnection conn = new GFXDClientConnection(connectionStr)) {
  conn.Open();
  // perform operations
  conn.Close();
}

// Open a new connection to the server with streaming disabled
using (GFXDClientConnection conn = new GFXDClientConnection(connectionStr)) {
  Dictionary<string, string> props = new Dictionary<string, string>();
  props.Add("disable-streaming", "true");
  conn.Open(props);
  // perform operations
  conn.Close();
}

Example: Connect to a locator with defaults and load-balance property

// Start a GemFire XD locator that starts a network server on localhost:1527
$ gfxd locator start -peer-discovery-port=3000
Starting GemFire XD Locator using peer discovery on: 0.0.0.0[3000]
Starting network server for GemFire XD Locator at address localhost/127.0.0.1[1527]
...

// Start a couple of GemFire XD servers with network servers on different ports
$ gfxd server start -locators=localhost[3000] -client-port=1528 -dir=server1
Starting GemFire XD Server using locators for peer discovery: localhost[3000]
Starting network server for GemFire XD Server at address localhost/127.0.0.1[1528]
...

$ gfxd server start -locators=localhost[3000] -client-port=1529 -dir=server2
Starting GemFire XD Server using locators for peer discovery: localhost[3000]
Starting network server for GemFire XD Server at address localhost/127.0.0.1[1529]
...

// Open a new connection to the locator having network server on localhost:1527.
// In default mode the driver will transparently query the locator and connect
// to one of the servers as per load balancing for the real data connection.
string host = "localhost";
int port = 1527;
string connectionStr = string.Format("server={0}:{1}", host, port);
using (GFXDClientConnection conn = new GFXDClientConnection(connectionStr)) {
  conn.Open();
  // perform operations
  conn.Close();
}

// Open a new connection to a specific server. Note that you must explicitly disable load-balancing using the connectino property.
int port2 = 1528;
string connectionStr2 = string.Format("server={0}:{1}", host, port2);
using (GFXDClientConnection conn = new GFXDClientConnection(connectionStr2)) {
  Dictionary<string, string> props = new Dictionary<string, string>();
  props.Add("load-balance", "false");
  conn.Open(props);
  // perform operations
  conn.Close();
}

Example: Connect to a cluster that has BUILTIN authentication enabled

// Start a GemFire XD locator with BUILTIN authentication.
// The system users should preferably be specified in gemfirexd.properties rather
// than on command-line as in the example below (see section ). System user
// in example below is "gem1" with password "gem1"
$ gfxd locator start -peer-discovery-port=3000 -auth-provider=BUILTIN -gemfirexd.user.gem1=gem1 -user=gem1 -password=gem1
Starting GemFire XD Locator using peer discovery on: 0.0.0.0[3000]
Starting network server for GemFire XD Locator at address localhost/127.0.0.1[1527]
...

// Start a couple of GemFire XD servers with network servers on different ports
$ gfxd server start -locators=localhost[3000] -auth-provider=BUILTIN -gemfirexd.user.gem1=gem1 -user=gem1 -password=gem1 -dir=server1 -client-port=1528
Starting GemFire XD Server using locators for peer discovery: localhost[3000]
Starting network server for GemFire XD Server at address localhost/127.0.0.1[1528]
...

$ gfxd server start -locators=localhost[3000] -auth-provider=BUILTIN -gemfirexd.user.gem1=gem1 -user=gem1 -password=gem1 -dir=server2 -client-port=1529
Starting GemFire XD Server using locators for peer discovery: localhost[3000]
Starting network server for GemFire XD Server at address localhost/127.0.0.1[1529]
...

// Create a new user (username/password as gem2/gem2) from GFXD command-shell.
$ gfxd
gfxd version 1.3.0 
gfxd> connect client 'localhost:1527;user=gem1;password=gem1';
gfxd> call sys.create_user('gemfirexd.user.gem2', 'gem2'); 
Statement executed. 
gfxd> quit;

// Open a new connection to the locator having network server on localhost:1527
// with username and password in the connection string.
string host = "localhost";
int port = 1527;
string user = "gem2";
string passwd = "gem2";
string connectionStr = string.Format("server={0}:{1};user={2};password={3}",
                                     host, port, user, passwd);
using (GFXDClientConnection conn = new GFXDClientConnection(connectionStr)) {
  conn.Open();
  // perform operations
  conn.Close();
}

// Open a new connection to the locator having network server on localhost:1527
// with username and password passed as properties.
string connectionStr2 = string.Format("server={0}:{1}", host, port);
using (GFXDClientConnection conn = new GFXDClientConnection(connectionStr2)) {
  Dictionary<string, string> props = new Dictionary<string, string>();
  props.Add("user", user);
  props.Add("password", passwd);
  conn.Open(props);
  // perform operations
  conn.Close();
}