public abstract class DistributedSystem extends Object implements StatisticsFactory
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()
. 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 is performed by contacting "locators" running on a given host and port. All DistributedSystems that are configured to use 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.
Users should never subclass this class.
Modifier and Type | Field and Description |
---|---|
protected static List<org.apache.geode.distributed.internal.InternalDistributedSystem> |
existingSystems
The instances of
DistributedSystem created in this VM. |
protected static Object |
existingSystemsLock
This lock must be changed to add or remove a system.
|
static String |
PROPERTIES_FILE_DEFAULT
The default value of
PROPERTIES_FILE_PROPERTY is
"gemfire.properties" . |
static String |
PROPERTIES_FILE_PROPERTY
The
PROPERTIES_FILE_PROPERTY is the system property that can be used to specify
the name of the properties file that the connect method will check for when it looks for a
properties file. |
static String |
PROPERTY_FILE
Deprecated.
As of 9.0, please use
getPropertiesFile() instead. |
static String |
SECURITY_PROPERTIES_FILE_DEFAULT
The default value of
SECURITY_PROPERTIES_FILE_PROPERTY is
"gfsecurity.properties" . |
static String |
SECURITY_PROPERTIES_FILE_PROPERTY
The
SECURITY_PROPERTIES_FILE_PROPERTY is the system property that can be used to
specify the name of the property file that the connect method will check for when it looks for
a property file. |
static String |
SECURITY_PROPERTY_FILE
Deprecated.
As of 9.0, please use
getSecurityPropertiesFile() instead. |
MAX_DESCRIPTORS_PER_TYPE
Modifier | Constructor and Description |
---|---|
protected |
DistributedSystem()
Creates a new instance of
DistributedSystem . |
Modifier and Type | Method and Description |
---|---|
protected static void |
addSystem(org.apache.geode.distributed.internal.InternalDistributedSystem newSystem) |
static DistributedSystem |
connect(Properties config)
Deprecated.
as of 6.5 use
CacheFactory.create() or ClientCacheFactory.create()
instead. |
protected static DistributedSystem |
connectForAdmin(Properties props)
Returns a connection to the distributed system that is appropriate for administration.
|
abstract void |
disconnect()
Deprecated.
as of 6.5 use
Cache.close(boolean) or ClientCache.close(boolean) instead. |
abstract DistributedMember |
findDistributedMember(String name)
Find the distributed member with the given name
|
abstract Set<DistributedMember> |
findDistributedMembers(InetAddress address)
Find the set of distributed members running on a given address
|
abstract Set<DistributedMember> |
getAllOtherMembers()
Returns a set of all the other members in this distributed system.
|
abstract CancelCriterion |
getCancelCriterion() |
protected static DistributedSystem |
getConnection(Properties config)
Returns an existing connection to the distributed system described by the given properties.
|
abstract DistributedMember |
getDistributedMember()
Returns the
DistributedMember that identifies this connection to the distributed
system. |
abstract Set<DistributedMember> |
getGroupMembers(String group)
Returns a set of all the members in the given group.
|
abstract long |
getId()
Deprecated.
getDistributedMember() provides an identity for this connection that is
unique across the entire distributed system. |
abstract LogWriter |
getLogWriter()
Deprecated.
|
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 String |
getPropertiesFile()
Returns the current value of
PROPERTIES_FILE_PROPERTY system property if set or the
default value PROPERTIES_FILE_DEFAULT . |
static URL |
getPropertiesFileURL()
Gets an
URL for the properties file, if one can be found, that the connect method
will use as its properties file. |
static URL |
getPropertyFileURL()
Deprecated.
As of 9.0, please use
getPropertiesFileURL() |
abstract DistributedSystem |
getReconnectedSystem()
Returns the new DistributedSystem if there was an auto-reconnect
|
abstract LogWriter |
getSecurityLogWriter()
Deprecated.
|
abstract Properties |
getSecurityProperties()
Returns the security specific configuration properties.
|
static String |
getSecurityPropertiesFile()
Returns the current value of
SECURITY_PROPERTIES_FILE_PROPERTY system property if set
or the default value SECURITY_PROPERTIES_FILE_DEFAULT . |
static URL |
getSecurityPropertiesFileURL()
Gets an
URL for the security properties file, if one can be found, that the
connect method will use as its properties file. |
abstract boolean |
isConnected()
Returns whether or not this
DistributedSystem is connected to the distributed
system. |
abstract boolean |
isReconnecting()
Test to see whether the DistributedSystem is in the process of reconnecting and recreating the
cache after it has been removed from the system by other members or has shut down due to
missing Roles and is reconnecting.
|
static void |
releaseThreadsSockets()
Frees up any socket resources owned by the calling thread.
|
protected static void |
removeSystem(org.apache.geode.distributed.internal.InternalDistributedSystem oldSystem) |
protected static void |
setEnableAdministrationOnly(boolean adminOnly)
|
static void |
setThreadsSocketPolicy(boolean conserveSockets)
Sets the calling thread's socket policy.
|
abstract void |
stopReconnecting()
Force the DistributedSystem to stop reconnecting.
|
abstract boolean |
waitUntilReconnected(long time,
TimeUnit units)
Wait for the DistributedSystem to finish reconnecting to the system and recreate the cache.
|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
createAtomicStatistics, createAtomicStatistics, createAtomicStatistics, createStatistics, createStatistics, createStatistics, findStatisticsByNumericId, findStatisticsByTextId, findStatisticsByType
createDoubleCounter, createDoubleCounter, createDoubleGauge, createDoubleGauge, createIntCounter, createIntCounter, createIntGauge, createIntGauge, createLongCounter, createLongCounter, createLongGauge, createLongGauge, createType, createTypesFromXml, findType
protected static volatile List<org.apache.geode.distributed.internal.InternalDistributedSystem> existingSystems
DistributedSystem
created in this VM. Presently only one connect
to a distributed system is allowed in a VM. This set is never modified in place (it is always
read only) but the reference can be updated by holders of existingSystemsLock
.protected static final Object existingSystemsLock
existingSystems
public static final String PROPERTIES_FILE_PROPERTY
PROPERTIES_FILE_PROPERTY
is the system property that can be used to specify
the name of the properties file that the connect method will check for when it looks for a
properties file. Unless the value specifies the fully qualified path to the file, the file will
be searched for, in order, in the following directories:
The default value is PROPERTIES_FILE_DEFAULT
. However if the
PROPERTIES_FILE_PROPERTY
is set then its value will be used instead of the
default. 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.
PROPERTIES_FILE_DEFAULT
,
getPropertiesFile()
,
Constant Field Valuespublic static final String PROPERTIES_FILE_DEFAULT
PROPERTIES_FILE_PROPERTY
is
"gemfire.properties"
. The location of the file will be resolved during connect as
described for PROPERTIES_FILE_PROPERTY
.PROPERTIES_FILE_PROPERTY
,
getPropertiesFile()
,
Constant Field Values@Deprecated public static final String PROPERTY_FILE
getPropertiesFile()
instead.PROPERTY_FILE
is the name of the properties file that the connect method will
check for when it looks for a properties file. The file will be searched for, in order, in the
following directories:
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.
getPropertiesFile()
public static final String SECURITY_PROPERTIES_FILE_PROPERTY
SECURITY_PROPERTIES_FILE_PROPERTY
is the system property that can be used to
specify the name of the property file that the connect method will check for when it looks for
a property file. Unless the value specifies the fully qualified path to the file, the file will
be searched for, in order, in the following directories:
The default value is SECURITY_PROPERTIES_FILE_DEFAULT
. However if the
SECURITY_PROPERTIES_FILE_PROPERTY
is set then its value will be used instead of
the default. 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.
SECURITY_PROPERTIES_FILE_DEFAULT
,
getSecurityPropertiesFile()
,
Constant Field Valuespublic static final String SECURITY_PROPERTIES_FILE_DEFAULT
SECURITY_PROPERTIES_FILE_PROPERTY
is
"gfsecurity.properties"
. The location of the file will be resolved during connect
as described for SECURITY_PROPERTIES_FILE_PROPERTY
.SECURITY_PROPERTIES_FILE_PROPERTY
,
getSecurityPropertiesFile()
,
Constant Field Values@Deprecated public static final String SECURITY_PROPERTY_FILE
getSecurityPropertiesFile()
instead.SECURITY_PROPERTY_FILE
is the name of the property file that the connect
method will check for when it looks for a security property file. The file will be searched
for, in order, in the following directories:
The default value of SECURITY_PROPERTY_FILE is "gfsecurity.properties"
. However if
the "gemfireSecurityPropertyFile" system property is set then its value is the value of
SECURITY_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.
getSecurityPropertiesFile()
protected DistributedSystem()
DistributedSystem
. This constructor is protected so that
it may only be invoked by subclasses.@Deprecated public static DistributedSystem connect(Properties config)
CacheFactory.create()
or ClientCacheFactory.create()
instead.The actual configuration attribute values used to connect comes from the following sources:
gemfire.
propertyName"
is defined and its value is not an empty string then its value will be used for the named
configuration attribute.
config
parameter
object and its value is not an empty string then its value will be used for that configuration
attribute.
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:
config
- The configuration properties used when connecting to
the distributed systemIllegalArgumentException
- 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
correctlyprotected static void addSystem(org.apache.geode.distributed.internal.InternalDistributedSystem newSystem)
protected static void removeSystem(org.apache.geode.distributed.internal.InternalDistributedSystem oldSystem)
public static void setThreadsSocketPolicy(boolean conserveSockets)
conserve-sockets
configuration property.conserveSockets
- If true
then calling thread will share socket connections
with other threads. If false
then calling thread will have its own sockets.public static void releaseThreadsSockets()
protected static DistributedSystem getConnection(Properties config)
config
- the properties used when creating a connection to the distributed systemprotected static DistributedSystem connectForAdmin(Properties props)
props
- the properties used when creating a connection to the distributed systemprotected static void setEnableAdministrationOnly(boolean adminOnly)
adminOnly
- whether this VM is dedicated to administration@Deprecated public abstract LogWriter getLogWriter()
LogWriter
used for logging information. See
logFile.LogWriter
used for logging informationIllegalStateException
- This VM has disconnected from the
distributed system.@Deprecated public abstract LogWriter getSecurityLogWriter()
LogWriter
used for logging security related information. See
logFile.LogWriter
used for logging security related informationIllegalStateException
- This VM has disconnected from the
distributed system.public abstract Properties getProperties()
public abstract Properties getSecurityProperties()
public abstract CancelCriterion getCancelCriterion()
@Deprecated public abstract void disconnect()
Cache.close(boolean)
or ClientCache.close(boolean)
instead.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.
public abstract boolean isConnected()
DistributedSystem
is connected to the distributed
system.DistributedSystem
is connected to the distributed systemdisconnect()
@Deprecated public abstract long getId()
getDistributedMember()
provides an identity for this connection that is
unique across the entire distributed system.@Deprecated public abstract String getMemberId()
getDistributedMember()
insteadSystemMembershipEvent.getMemberId()
public abstract DistributedMember getDistributedMember()
DistributedMember
that identifies this connection to the distributed
system.public abstract Set<DistributedMember> getAllOtherMembers()
public abstract Set<DistributedMember> getGroupMembers(String group)
group
- the group to which the distributed members to find belongpublic abstract Set<DistributedMember> findDistributedMembers(InetAddress address)
address
- the address of the distributed members to findpublic abstract DistributedMember findDistributedMember(String name)
name
- the name of the distributed member to findpublic abstract String getName()
public static String getPropertiesFile()
PROPERTIES_FILE_PROPERTY
system property if set or the
default value PROPERTIES_FILE_DEFAULT
.PROPERTIES_FILE_PROPERTY
system property if set or the
default value PROPERTIES_FILE_DEFAULT
PROPERTIES_FILE_PROPERTY
,
PROPERTIES_FILE_DEFAULT
public static String getSecurityPropertiesFile()
SECURITY_PROPERTIES_FILE_PROPERTY
system property if set
or the default value SECURITY_PROPERTIES_FILE_DEFAULT
.SECURITY_PROPERTIES_FILE_PROPERTY
system property if set
or the default value SECURITY_PROPERTIES_FILE_DEFAULT
SECURITY_PROPERTIES_FILE_PROPERTY
,
SECURITY_PROPERTIES_FILE_DEFAULT
public static URL getPropertiesFileURL()
URL
for the properties file, if one can be found, that the connect method
will use as its properties file.
See PROPERTIES_FILE_PROPERTY
for information on the name of the properties file and
what locations it will be looked for in.
URL
that names the GemFire property file. Null is returned if no
property file was found.PROPERTIES_FILE_PROPERTY
,
PROPERTIES_FILE_DEFAULT
,
getPropertiesFile()
@Deprecated public static URL getPropertyFileURL()
getPropertiesFileURL()
URL
for the property file, if one can be found, that the connect method
will use as its property file.
See PROPERTIES_FILE_PROPERTY
for information on the name of the property file and what
locations it will be looked for in.
URL
that names the GemFire property file. Null is returned if no
property file was found.getPropertiesFileURL()
public static URL getSecurityPropertiesFileURL()
URL
for the security properties file, if one can be found, that the
connect method will use as its properties file.
See SECURITY_PROPERTIES_FILE_PROPERTY
for information on the name of the properties
file and what locations it will be looked for in.
URL
that names the GemFire security properties file. Null is returned if
no properties file was found.SECURITY_PROPERTIES_FILE_PROPERTY
,
SECURITY_PROPERTIES_FILE_DEFAULT
,
getSecurityPropertiesFile()
public abstract boolean isReconnecting()
This will also return true if the DistributedSystem has finished reconnecting. When reconnect
has completed you can use getReconnectedSystem()
to retrieve the new
distributed system.
public abstract boolean waitUntilReconnected(long time, TimeUnit units) throws InterruptedException
time
- amount of time to wait, or -1 to wait foreverunits
- the units associated with the timeInterruptedException
- if the thread is interrupted while waitingpublic abstract void stopReconnecting()
public abstract DistributedSystem getReconnectedSystem()