Embedded Peer-to-Peer Deployment

The embedded, peer-to-peer distributed system (also known as an embedded cluster) is the building block for all vFabric SQLFire installations. With an embedded cluster, the core SQLFire engine is embedded alongside an existing Java application in the same JVM. When the application initiates a connection to SQLFire using the peer JDBC driver, it starts a SQLFire 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 SQLFire security framework after they are authenticated.

An embedded SQLFire peer can optionally provide network server functionality for applications that need to support connectivity from JDBC or ADO.NET clients. Or, you can embed SQLFire 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 SQLFire peer also provides network services.

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

Note: In this release of SQLFire, ADO.NET clients cannot connect as peers.

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 SQLFire 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 SQLFire peers. For example, if you embed SQLFire in a cluster of Java application servers, each application server and the associated SQLFire 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 SQLFire 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. SQLFire 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 SQLFire Cache Strategies).


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

Example Code for Embedding SQLFire Members

If your application embeds a SQLFire 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 SQLFire in the main thread before any other thread attempts to connect to the cluster. Starting SQLFire Servers with the FabricServer Interface summarizes the steps involved in using the FabricServiceManager API.

For example, to embed a SQLFire 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 SQLFire 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 SQLFire accessor. This is a SQLFire 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:sqlfire:";
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�?);