Embedded Peer-to-Peer Deployment

The embedded, peer-to-peer distributed system (also known as an embedded cluster) is the building block for all GemFire XD installations. With an embedded cluster, the core GemFire XD engine is embedded alongside an existing Java application in the same JVM. When the application initiates a connection to GemFire XD using the peer JDBC driver, it starts a GemFire XD peer member that joins other peers in the same cluster.

Understanding Embedded Peer-to-Peer Deployment

The embedded peer-to-peer model provides embedded Java applications with default one-hop or no-hop access to data. Each peer member communicates directly with the other members of the cluster and can host data as necessary, persist data to disk (if it is a data store), and participate in distributed queries. All peers are treated as "fully authorized" by the GemFire XD security framework after they are authenticated.

An embedded GemFire XD peer can optionally provide network server functionality for applications that need to support connectivity from JDBC, ODBC, or ADO.NET thin clients. Or, you can embed GemFire XD in a cluster of application servers such as Apache Tomcat or Oracle WebLogic, which provide their own network server functionality. A single attribute in the JDBC peer driver connection determines whether the GemFire XD peer also provides network services.

Embedding GemFire XD peer services is supported only for Java applications. Existing Java applications can easily switch to using an embedded GemFire XD peer by including the required GemFire XD libraries and specifying the GemFire XD JDBC peer client URL.

Deciding When to Use Embedded Peer-to-Peer

Here are typical scenarios in which you would use the embedded peer-to-peer model:
  • Many applications frequently accessing content directly from within the process heap (for example, session state data or other Web content). The embedded peer-to-peer model automatically provides one-hop or no-hop access to data. The GemFire XD JDBC thin-client driver also supports one-hop access for lightweight client applications.
  • More convenient from an administration and management standpoint. With an embedded cluster, there is no need to manage any external processes in order to deploy GemFire XD peers. For example, if you embed GemFire XD in a cluster of Java application servers, each application server and the associated GemFire XD peer share the same process heap.
  • Applications requiring a few peer clients (as opposed to hundreds). Deploying many peers increases the buffering and socket overhead for each member. Having numerous peers can also strain the group membership system coordinator, and it increases the overhead necessary for detecting failures. In an embedded cluster deployment, all GemFire XD transactions and distributed locks are maintained by the peers themselves. This is in contrast to the client-server deployment model, in which clients are required to execute server-side code (such as stored procedures) in order to acquire locks or execute transactions.
  • Partitioned caching applications in which a small number of "feed" clients push data to an RDBMS at a very fast rate. This scenario is particularly suited to embedded peer-to-peer. GemFire XD peer members dispatch messages to other peers synchronously by default, and with minimal context-switching. This provides the lowest possible latency and offers the highest distribution throughput for both replicated caching as well as partitioned caching applications. It also offers the lowest distribution latency, which useful for latency-sensitive "feed" clients.

    Other (non-"feed") clients should connect to the distributed cache cluster as non-peers (see GemFire XD Cache Strategies).


In a partitioned caching application, updates to distributed data are synchronously or asynchronously propagated to a backend database server using the GemFire XD caching framework (see GemFire XD Cache Strategies).

Example Code for Embedding GemFire XD Members

If your application embeds a GemFire XD member of any type (a peer client, server, or locator), you should use the FabricServiceManager API to embed the required type. The application should embed GemFire XD in the main thread before any other thread attempts to connect to the cluster. Starting GemFire XD Servers with the FabricServer Interface summarizes the steps involved in using the FabricServiceManager API.

For example, to embed a GemFire XD locator inside an application:

Properties props = new Properties();
// add desired properties if required.
FabricLocator locator = FabricServiceManager.getFabricLocatorInstance();
locator.start("localhost", 22343, props);

A second application could use the above locator for discover. This example code connects using a locator, and also adds the embedded GemFire XD member to server groups "sg1" and "sg2:"

Properties props = new Properties();
// add desired properties if required.
props.setProperty("server-groups", "sg1,sg2");
props.setProperty("locators", "localhost[22343]");
props.setProperty("host-data", "true"); // not required as the default
                                        // is true

FabricServer server = FabricServiceManager.getFabricServerInstance();

In some cases you may want to embed a GemFire XD accessor. This is a GemFire XD member that does not host data, but otherwise participates in the cluster. This code starts an accessor and also uses the locator for discovery:

Properties props = new Properties();
// add desired properties if required.
props.setProperty("server-groups", "sg3");
props.setProperty("locators", "localhost[22343]");
props.setProperty("host-data", "false");
FabricServer server = FabricServiceManager.getFabricServerInstance();

After starting a peer client, locator, or accessor as above, an application can obtain a connection:

String embedConnURL = "jdbc:gemfirexd:";
Properties connProps = new Properties();
connProps.setProperty("user", "tom");
connProps.setProperty("password", "tomspassword");
Connection conn = DriverManager.getConnection(embedConnURL, connProps);

// create a table using this connection
Statement s = conn.createStatement();
st.execute("create table customer
      (id int not null, name varchar(100) not null");