SQLFire 1.0.2

com.vmware.sqlfire
Interface FabricServer

All Superinterfaces:
FabricService

public interface FabricServer
extends FabricService

A FabricServer is a singleton that allows remote clients to connect to the SQLFire cluster(distributed system). It is a peer member of the distributed system. A FabricServer is started by invoking the start(java.util.Properties) method with configuration parameters as described below. Use FabricServiceManager to get a reference to the FabricServer singleton instance.

When a program calls start(java.util.Properties), if start-locator is configured then an embedded locator is started. Else, among other things a distribution manager is started that will attempt to join the distributed system either using the locators configuration parameter or using mcast (if mcast-port is set). All connections that are configured to use the same multicast address/port and the same locators are part of the same distributed FabricServer system.

The current version supports only a single instance of FabricServer 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.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 to access the singleton instance which can be stopped and reconnected using different Properties for different distributed system connections.

Note that the application can also start/stop the FabricServer instance when creating the first JDBC connection with the requisite boot properties. The properties used to bootstrap the server instance is same as the connection properties.

Configuration

Configuration properties are listed and documented at Connection Attributes

Example:

    Properties p = new Properties();
    p.setProperty("mcast-port", "12444"); // All members in the cluster use the same mcast-port
    p.setProperty("conserve-sockets", "false"); // Don't conserve socket connections; Go fast
    p.setProperty("statistic-sampling-enabled", "true"); // Write out performance statistics

    final FabricServer server = FabricServiceManager.getFabricServerInstance();
    server.start(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 'sqlfire.properties' or defined as system properties. SQLFire looks for this file in the current working directory, followed by 'sqlfire.system.home' directory and then in 'user.home' directory. The file name can be overridden using the system property -Dsqlfire.properties=. 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 "sqlfire.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 FabricServer API are the following:


Nested Class Summary
 
Nested classes/interfaces inherited from interface com.vmware.sqlfire.FabricService
FabricService.State
 
Field Summary
 
Fields inherited from interface com.vmware.sqlfire.FabricService
NETSERVER_DEFAULT_PORT, STOP_NETWORK_SERVERS
 
Method Summary
 void start(Properties bootProperties)
          Start the SQLFire server singleton instance if not already started.
 void start(Properties bootProperties, boolean ignoreIfStarted)
          Start the SQLFire server singleton instance if not already started.
 FabricService.State status()
          Returns the fabric server status.
 
Methods inherited from interface com.vmware.sqlfire.FabricService
getAllNetworkServers, startNetworkServer, stop, stopAllNetworkServers
 

Method Detail

start

void start(Properties bootProperties)
           throws SQLException
Start the SQLFire server singleton instance if not already started. In case the server 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.

Properties can be also configured in a file called 'sqlfire.properties' or defined as system properties. SQLFire looks for this file in 'sqlfire.user.home' directory, if set, otherwise in the current working directory, followed by 'user.home' directory. The file name can be overridden using the system property -Dsqlfire.properties=. 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 "sqlfire.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 server

Parameters:
bootProperties - Driver boot properties. If non-null, overrides default properties in 'sqlfire.properties'.
Throws:
SQLException

start

void start(Properties bootProperties,
           boolean ignoreIfStarted)
           throws SQLException
Start the SQLFire server singleton instance if not already started. Initiates and establishes connections with all the other peer members.

Properties can be also configured in a file called 'sqlfire.properties' or defined as system properties. SQLFire looks for this file in 'sqlfire.user.home' directory, if set, otherwise in the current working directory, followed by 'user.home' directory. The file name can be overridden using the system property -Dsqlfire.properties=. 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 "sqlfire.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 server

Parameters:
bootProperties - Driver boot properties. If non-null, overrides default properties in 'sqlfire.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 fabric server status.

Specified by:
status in interface FabricService
Returns:
FabricService.State

SQLFire 1.0.2

Copyright © 2010-2012 VMware, Inc. All rights reserved.