GemFire 6.5

com.gemstone.gemfire.distributed
Class DistributedSystem

java.lang.Object
  extended by com.gemstone.gemfire.distributed.DistributedSystem
All Implemented Interfaces:
StatisticsFactory, StatisticsTypeFactory

public abstract class DistributedSystem
extends Object
implements StatisticsFactory

A "connection" to a GemFire distributed system. A DistributedSystem is created by invoking the connect(java.util.Properties) method with a configuration as described below. A DistributedSystem is used when calling CacheFactory.create(com.gemstone.gemfire.distributed.DistributedSystem). This class should not be confused with the AdminDistributedSystem interface that is used for administering a distributed system.

When a program connects to the distributed system, a "distribution manager" is started in this VM and the other members of the distributed system are located. This discovery can be performed using either IP multicast (default) or by contacting "locators" running on a given host and port. All connections that are configured to use the same multicast address/port and the same locators are part of the same distributed system.

The current version of GemFire only supports creating one DistributedSystem per virtual machine. Attempts to connect to multiple distributed systems (that is calling connect(java.util.Properties) multiple times with different configuration Properties) will result in an IllegalStateException being thrown (if connect is invoked multiple times with equivalent Properties, then the same instance of DistributedSystem will be returned). A common practice is to connect to the distributed system and store a reference to the DistributedSystem object in a well-known location such as a static variable. This practice provides access to the DistributedSystem slightly faster than invoking connect multiple times. Note that it is always advisable to disconnect() from the distributed system when a program will no longer access it. Disconnecting frees up certain resources and allows your application to connect to a different distributed system, if desirable.

Configuration

There are a number of configuration properties that can be set when a program connects to a distributed system.

Distribution Configuration Properties

name
Description: a symbolic name that can be used by administrators to help identify a connection to the distributed system.
Default: ""
mcast-port
Description: The port used for multicast networking. If zero, then multicast will be disabled and locators must be used to find the other members of the distributed system. If "mcast-port" is zero and "locators" is "" then this distributed system will be isolated from all other vms and administration consoles.
Default: "10334"
mcast-address
Description: The IP address used for multicast networking. If mcast-port is zero, then mcast-address is ignored.
Default: "239.192.81.1"
mcast-ttl
Description: Determines how far through your network the multicast packets used by GemFire will propagate.
Default: "32"
Allowed values: 0..255
Since: 4.1
mcast-send-buffer-size
Description: Sets the size of the socket buffer used for outgoing multicast transmissions.
Default: "65535"
Allowed values: 2048..Operating System maximum
Since: 5.0
mcast-recv-buffer-size
Description: Sets the size of the socket buffer used for incoming multicast transmissions. You should set this high if there will be high volumes of messages.
Default: "1048576"
Allowed values: 2048..Operating System maximum
Since: 5.0
mcast-flow-control
Description: Configures the flow-of-control protocol for multicast messaging. There are three settings that are separated by commas: byteAllowance (integer), rechargeThreshold (float) and rechargeBlockMs (integer). The byteAllowance determines how many bytes can be sent without a recharge from other processes. The rechargeThreshold tells receivers how low the sender's initial to remaining allowance ratio should be before sending a recharge. The rechargeBlockMs tells the sender how long to wait for a recharge before explicitly requesting one.
Default: "1048576,0.25,5000"
Allowed values: 100000-maxInt, 0.1-0.5, 500-60000
Since: 5.0
udp-send-buffer-size
Description: Sets the size of the socket buffer used for outgoing udp point-to-point transmissions.
Default: "65535"
Allowed values: 2048..Operating System maximum
Since: 5.0
udp-recv-buffer-size
Description: Sets the size of the socket buffer used for incoming udp point-to-point transmissions. Note: if multicast is not enabled and disable-tcp is not enabled, a reduced default size of 65535 is used.
Default: "1048576 if multicast is enabled or disable-tcp is true, 131071 if not"
Allowed values: 2048..Operating System maximum
Since: 5.0
udp-fragment-size
Description: When messages are sent over datagram sockets, GemFire breaks large messages down into fragments for transmission. This property sets the maximum fragment size for transmission.
Default: "60000"
Allowed values: 1000..60000
Since: 5.0
disable-tcp
Description: Turns off use of tcp/ip sockets, forcing the cache to use datagram sockets for all communication. This is useful if you have a large number of processes in the distributed cache since it eliminates the per-connection reader-thread that is otherwise required. However, udp communications are somewhat slower than tcp/ip communications due to the extra work required in Java to break messages down to transmittable sizes, and the extra work required to guarantee message delivery.
Default: "false"
Allowed values: true or false
Since: 5.0
tcp-port
Description: A 16-bit integer that determines the tcp/ip port number to listen on for cache communications. If zero, the operating system will select an available port to listen on. Each process on a machine must have its own tcp-port. Note that some operating systems restrict the range of ports usable by non-privileged users, and using restricted port numbers can cause runtime errors in GemFire startup.
Default: "0"
Allowd values: 0..65535
Since: 5.0
member-timeout
Description: Sets the timeout interval, in milliseconds, used to determine whether another process is alive or not. When another process appears to be gone, GemFire tries five times to contact it before giving up. This property sets the timeout interval for each of these attempts.
Default: "5000"
Allowed values: 1000-600000
Since: 5.0
bind-address
Description: The IP address that this distributed system's server sockets will listen on. If set to an empty string then the local machine's default address will be listened on.
Default: ""
membership-port-range
Description: The allowed range of ports for use in forming an unique membership identifier (UDP) and for failure detection purposes (TCP). This range is given as two numbers separated by a minus sign.
Default: 1024-65535
locators
Description: A list of locators (host and port) that are used to find other member of the distributed system. If mcast-port is non-zero, this property is ignored. This attribute's value is a possibly empty comma separated list. Each element must be of the form "hostName[portNum]" and may be of the form "host:bindAddress[port]" if a specific bind address is to be used on the locator machine. The square brackets around the portNum are literal character and must be specified.

Since IPv6 bind addresses may contain colons, you may use an at symbol instead of a colon to separate the host name and bind address. For example, "server1@fdf0:76cf:a0ed:9449::5[12233]" specifies a locator running on "server1" and bound to fdf0:76cf:a0ed:9449::5 on port 12233.

If "mcast-port" is zero and "locators" is "" then this distributed system will be isolated from all other vms and administration consoles.

Default: ""
start-locator
Description: A host name or bind-address and port ("host[port],peer=,server=") that are used to start a locator in the same process as the DistributedSystem. The locator is started when the DistributedSystem connects, and is stopped when the DistributedSystem disconnects. To start a locator that is not tied to the DistributedSystem's lifecycle, see the Locator class in this same package.

The peer and server parameters are optional. They specify whether the locator can be used for peers to discover eachother, or for clients to discover peers. By default both are true.

Default: "" (doesn't start a locator)
ssl-enabled
Description: If true, all gemfire socket communication is configured to use SSL through JSSE.
Default: "false"
ssl-protocols
Description: A space seperated list of the SSL protocols to enable. Those listed must be supported by the available providers.
Default: "any"
ssl-ciphers
Description: A space seperated list of the SSL cipher suites to enable. Those listed must be supported by the available providers.
Default: "any"
ssl-require-authentication
Description: If false, allow ciphers that do not require the client side of the connection to be authenticated.
Default: "true"
ack-wait-threshold
Description: The number of seconds the distributed system will wait for a message to be acknowledged before it sends a warning level alert to signal that something might be wrong with the system node that is unresponsive. After sending this alert the waiter continues to wait. The alerts are logged in the log as warnings and, if a GemFire Administration Console is running, will cause a console alert to be signalled.
Default: "15"
Allowed values: 1..2147483647
ack-severe-alert-threshold
Description: The number of seconds the distributed system will wait after the ack-wait-threshold for a message to be acknowledged before it issues an alert at severe level. The default value is zero, which turns off this feature.

when ack-severe-alert-threshold is used, GemFire will also initiate additional checks to see if the process is alive. These checks will begin when the ack-wait-threshold is reached and will continue until GemFire has been able to communicate with the process and ascertain its status.

Default: "0"
Allowed values: 0..2147483647
conserve-sockets
Description: If "true" then a minimal number of sockets will be used when connecting to the distributed system. This conserves resource usage but can cause performance to suffer. If "false" then every application thread that sends distribution messages to other members of the distributed system will own its own sockets and have exclusive access to them. The length of time a thread can have exclusive access to a socket can be configured with "socket-lease-time".
Default: "true"
Allowed values: true|false
Since: 4.1
socket-lease-time
Description: The number of milliseconds a thread can keep exclusive access to a socket that it is not actively using. Once a thread loses its lease to a socket it will need to re-acquire a socket the next time it sends a message. A value of zero causes socket leases to never expire. This property is ignored if "conserve-sockets" is true.
Default: "15000"
Allowed values: 0..600000
Since: 4.1
socket-buffer-size
Description: The size of each socket buffer, in bytes. Smaller buffers conserve memory. Larger buffers can improve performance; in particular if large messages are being sent.
Default: "32768"
Allowed values: 128..16777215
Since: 4.1
conflate-events
Description: This is a client-side property that is passed to the server. Allowable values are "server", "true", and "false". With the "server" setting, this client's servers use their own client queue conflation settings. With a "true" setting, the servers disregard their own configuration and enable conflation of events for all regions for the client. A "false" setting causes the client's servers to disable conflation for all regions for the client.
Default: "server"
Since: 5.7
durable-client-id
Description: The id to be used by this durable client. When a durable client connects to a server, this id is used by the server to identify it. The server will accumulate updates for a durable client while it is disconnected and deliver these events to the client when it reconnects.
Default: ""
Since: 5.5
durable-client-timeout
Description: The number of seconds a disconnected durable client is kept alive and updates are accumulated for it by the server before it is terminated.
Default: "300"
Since: 5.5
security-
Description: Mechanism to define client credentials. All tags with "security-" prefix is packaged together as security properties and passed as an argument to getCredentials of Authentication module. These tags cannot have null values.
Default: Optional
Allowed values: any string
*
security-client-auth-init
Description: Authentication module name for Clients that requires to act upon credentials read from the gemfire.properties file. Module must implement AuthInitialize interface.
Default: "gemfire.jar:authInit"
Allowed values: jar file:class name
status-monitoring-enabled
Description: "true" causes the status monitor to be started. This allows the status of the member to be monitored. "false" does not start the status monitor so status monitoring is not enabled.
Default: "false"
Allowed values: true|false
status-monitoring-port
Description: The port used for the status monitor to listen for status requests.
Default: "0"
Allowed values: 0..65535
delta-propagation
Description: "true" indicates that server propagates delta generated from Delta type of objects. If "false" then server propagates full object but not delta.
Default: "true"
Allowed values: true|false
Network Partitioning Detection
enable-network-partition-detection
Description: Turns on network partitioning detection algorithms, which detect loss of processes eligible to function as the membership coordinator and correlates it with loss of a selected lead member.
Default: "false"
departure-correlation-window
Description: Establishes the number of seconds of process failure history kept by the system for correlating loss of processes eligible to be the membership coordinator and the lead member.
Default: "1800"
Logging Configuration Properties
log-file
Description: Name of the file to write logging messages to. If the file name if "" (default) then messages are written to standard out.
Default: ""
log-level
Description:The type of log messages that will actually write to the log file.
Default: "config"
Allowed values: all|finest|finer|fine|config|info|warning|severe|none
statistic-sampling-enabled
Description: "true" causes the statistics to be sampled periodically and operating system statistics to be fetched each time a sample is taken. "false" disables sampling which also disables operating system statistic collection. Non OS statistics will still be recorded in memory and can be viewed by administration tools. However, charts will show no activity and no statistics will be archived while sampling is disabled.
Default: "false"
Allowed values: true|false
statistic-sample-rate
Description:The rate, in milliseconds, at which samples of the statistics will be taken.
Default: "1000"
Allowed values: 100..60000
statistic-archive-file
Description: The file that statistic samples are written to. An empty string (default) disables statistic archival.
Default: ""
enable-time-statistics
Description: "true" causes additional time-based statistics to be gathered for gemfire operations. This can aid in discovering where time is going in cache operations, albeit at the expense of extra clock probes on every operation. "false" disables the additional time-based statistics.
Default: "false"
Allowed values: true or false
Since: 5.0
log-file-size-limit
Description: Limits, in megabytes, how large the current log file can grow before it is closed and logging rolls on to a new file. Set to zero to disable log rolling.
Default: "0"
Allowed values: 0..1000000
log-disk-space-limit
Description: Limits, in megabytes, how much disk space can be consumed by old inactive log files. When the limit is exceeded the oldest inactive log file is deleted. Set to zero to disable automatic log file deletion.
Default: "0"
Allowed values: 0..1000000
archive-file-size-limit
Description: Limits, in megabytes, how large the current statistic archive file can grow before it is closed and archival rolls on to a new file. Set to zero to disable archive rolling.
Default: "0"
Allowed values: 0..1000000
archive-disk-space-limit
Description: Limits, in megabytes, how much disk space can be consumed by old inactive statistic archive files. When the limit is exceeded the oldest inactive archive is deleted. Set to zero to disable automatic archive deletion.
Default: "0"
Allowed values: 0..1000000
roles
Description: Specifies the application roles that this member performs in the distributed system. This is a comma delimited list of user-defined strings. Any number of members can be configured to perform the same role, and a member can be configured to perform any number of roles.
Default: ""
Since: 5.0
max wait time before reconnect
Description: Specifies the maximum number of milliseconds to wait for the distributed system to reconnect in case of required role loss. The system will attempt to reconnect more than once, and this timeout period applies to each reconnection attempt.
Default: "10000 milliseconds"
Since: 5.0
max number of reconnect tries
Description: Specifies the maximum number or times to attempt to reconnect to the distributed system when required roles are missing.
Default: "3"
Since: 5.0
Licensing Configuration Properties
license-type
Description: The type of license this distributed system member will use. All member of a distributed system must use the same type of license.
Default: "evaluation"
Allowed values: evaluation|development|production
license-file
Description: The license file that contains the license this distributed system member will use. If a license file can not be located the distributed system connection will fail. The license file can exist in either the current directory or the product directory. If a license file is not found then it will be searched for using ClassLoader.getResource(java.lang.String).
Default: "gemfireLicense.zip"
Cache Configuration Properties
cache-xml-file
Description: Specifies the name of the XML file or resource to initialize the cache with when it is created. Create will first look for a file that matches the value of this property. If a file is not found then it will be searched for using ClassLoader.getResource(java.lang.String). If the value of this property is the empty string (""), then the cache will not be declaratively initialized.
Default: "cache.xml"
Asynchronous Message Properties
async-distribution-timeout
Description: The number of milliseconds before a publishing process should attempt to distribute a cache operation before switching over to asynchronous messaging for this process. To enable asynchronous messaging, the value must be set above zero. If a thread that is publishing to the cache exceeds this value when attempting to distribute to this process, it will switch to asynchronous messaging until this process catches up, departs, or some specified limit is reached, such as async-queue-timeout or async-max-queue-size.
Default: "0"
Allowed values: 0..60000
async-queue-timeout
Description: The number of milliseconds a queuing publisher may enqueue asynchronous messages without any distribution to this process before that publisher requests this process to depart. If a queuing publisher has not been able to send this process any cache operations prior to the timeout, this process will attempt to close its cache and disconnect from the distributed system.
Default: "60000"
Allowed values: 0..86400000
async-max-queue-size
Description: The maximum size in megabytes that a publishing process should be allowed to asynchronously enqueue for this process before asking this process to depart from the distributed system.
Default: "8"
Allowed values: 0..1024

Since:
3.0

Field Summary
static String PROPERTY_FILE
          The PROPERTY_FILE is the name of the property file that the connect method will check for when it looks for a property file.
 
Fields inherited from interface com.gemstone.gemfire.StatisticsTypeFactory
MAX_DESCRIPTORS_PER_TYPE
 
Method Summary
static DistributedSystem connect(Properties config)
          Deprecated. as of 6.5 use CacheFactory.create(com.gemstone.gemfire.distributed.DistributedSystem) or ClientCacheFactory.create() instead.
abstract  void disconnect()
          Deprecated. as of 6.5 use Cache.close(boolean) or ClientCache.close(boolean) instead.
abstract  CancelCriterion getCancelCriterion()
           
abstract  DistributedMember getDistributedMember()
          Returns the DistributedMember that identifies this connection to the distributed system.
abstract  long getId()
          Deprecated. getDistributedMember() provides an identity for this connection that is unique across the entire distributed system.
abstract  LogWriter getLogWriter()
          Returns the LogWriter used for logging information.
abstract  String getMemberId()
          Deprecated. as of GemFire 5.0, use getDistributedMember() instead
abstract  String getName()
          Returns the name of this connection to the distributed system.
abstract  Properties getProperties()
          Returns the configuration properties.
static URL getPropertyFileURL()
          Gets an URL for the property file, if one can be found, that the connect method will use as its property file.
abstract  LogWriter getSecurityLogWriter()
          Returns the LogWriter used for logging security related information.
abstract  Properties getSecurityProperties()
          Returns the security specific configuration properties.
abstract  boolean isConnected()
          Returns whether or not this DistributedSystem is connected to the distributed system.
static void releaseThreadsSockets()
          Frees up any socket resources owned by the calling thread.
static void setThreadsSocketPolicy(boolean conserveSockets)
          Sets the calling thread's socket policy.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.gemstone.gemfire.StatisticsFactory
createAtomicStatistics, createAtomicStatistics, createAtomicStatistics, createStatistics, createStatistics, createStatistics, findStatisticsByNumericId, findStatisticsByTextId, findStatisticsByType
 
Methods inherited from interface com.gemstone.gemfire.StatisticsTypeFactory
createDoubleCounter, createDoubleCounter, createDoubleGauge, createDoubleGauge, createIntCounter, createIntCounter, createIntGauge, createIntGauge, createLongCounter, createLongCounter, createLongGauge, createLongGauge, createType, createTypesFromXml, findType
 

Field Detail

PROPERTY_FILE

public static final String PROPERTY_FILE
The PROPERTY_FILE is the name of the property file that the connect method will check for when it looks for a property file. The file will be searched for, in order, in the following directories:
  1. the current directory
  2. the home directory
  3. the class path
Only the first file found will be used.

The default value of PROPERTY_FILE is "gemfire.properties". However if the "gemfirePropertyFile" system property is set then its value is the value of 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.

Since:
5.0
Method Detail

connect

public static DistributedSystem connect(Properties config)
Deprecated. as of 6.5 use CacheFactory.create(com.gemstone.gemfire.distributed.DistributedSystem) or ClientCacheFactory.create() instead.

Connects to a GemFire distributed system with a configuration supplemented by the given properties.

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

  1. System properties. If a system property named "gemfire.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 config 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 name of the property file can be specified using the "gemfirePropertyFile" system property. If the system property is set to a relative file name then it is searched for in following locations. If the system property is set to an absolute file name then that file is used as the property file. If the system property is not set, then the name of the property file defaults to "gemfire.properties". The configuration file is searched for in the following locations:

  1. Current directory (directory in which the VM was launched)
  2. User's home directory
  3. Class path (loaded as a system resource)
If the configuration file cannot be located, then the property will have its default value as described above.

Parameters:
config - The configuration properties used when connecting to the distributed system
Throws:
IllegalArgumentException - If config contains an unknown configuration property or a configuration property does not have an allowed value. Note that the values of boolean properties are parsed using Boolean.valueOf(java.lang.String). Therefore all values other than "true" values will be considered false -- an exception will not be thrown.
IllegalStateException - If a DistributedSystem with a different configuration has already been created in this VM or if this VM is administering a distributed system.
GemFireIOException - Problems while reading configuration properties file or while opening the log file.
GemFireConfigException - The distribution transport is not configured correctly
LicenseException - A license to run could not be obtained

setThreadsSocketPolicy

public static void setThreadsSocketPolicy(boolean conserveSockets)
Sets the calling thread's socket policy. This value will override that default set by the conserve-sockets configuration property.

Parameters:
conserveSockets - If true then calling thread will share socket connections with other threads. If false then calling thread will have its own sockets.
Since:
4.1

releaseThreadsSockets

public static void releaseThreadsSockets()
Frees up any socket resources owned by the calling thread.

Since:
4.1

getLogWriter

public abstract LogWriter getLogWriter()
Returns the LogWriter used for logging information. See logFile.

Throws:
IllegalStateException - This VM has disconnected from the distributed system.

getSecurityLogWriter

public abstract LogWriter getSecurityLogWriter()
Returns the LogWriter used for logging security related information. See logFile.

Throws:
IllegalStateException - This VM has disconnected from the distributed system.
Since:
5.5

getProperties

public abstract Properties getProperties()
Returns the configuration properties.

Returns:
the configuration Properties

getSecurityProperties

public abstract Properties getSecurityProperties()
Returns the security specific configuration properties.

Returns:
the configuration Properties
Since:
5.5

getCancelCriterion

public abstract CancelCriterion getCancelCriterion()
Returns:
the cancel criterion for this system

disconnect

public abstract void disconnect()
Deprecated. as of 6.5 use Cache.close(boolean) or ClientCache.close(boolean) instead.

Disconnects from this distributed system. This operation will close the distribution manager and render the Cache and all distributed collections obtained from this distributed system inoperable. After a disconnect has completed, a VM may connect to another distributed system.

Attempts to access a distributed system after a VM has disconnected from it will result in an IllegalStateException being thrown.


isConnected

public abstract boolean isConnected()
Returns whether or not this DistributedSystem is connected to the distributed system.

See Also:
disconnect()

getId

@Deprecated
public abstract long getId()
Deprecated. getDistributedMember() provides an identity for this connection that is unique across the entire distributed system.

Returns the id of this connection to the distributed system.


getMemberId

@Deprecated
public abstract String getMemberId()
Deprecated. as of GemFire 5.0, use getDistributedMember() instead

Returns a string that uniquely identifies this connection to the distributed system.

Since:
4.0
See Also:
SystemMembershipEvent.getMemberId()

getDistributedMember

public abstract DistributedMember getDistributedMember()
Returns the DistributedMember that identifies this connection to the distributed system.

Returns:
the member that represents this distributed system connection.
Since:
5.0

getName

public abstract String getName()
Returns the name of this connection to the distributed system.


getPropertyFileURL

public static URL getPropertyFileURL()
Gets an URL for the property file, if one can be found, that the connect method will use as its property file.

See PROPERTY_FILE for information on the name of the property file and what locations it will be looked for in.

Returns:
a URL that names the GemFire property file. Null is returned if no property file was found.
Since:
5.0

GemFire 6.5

Copyright © 2002-2010 GemStone Systems, Inc. All Rights Reserved.