DistributedSystem (Apache Geode 1.6.0)
Date: 2018-04-23

org.apache.geode.distributed

## Class DistributedSystem

- java.lang.Object
- - org.apache.geode.distributed.DistributedSystem

- All Implemented Interfaces:
    StatisticsFactory, StatisticsTypeFactory

      public abstract class DistributedSystem
      extends java.lang.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(org.apache.geode.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 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.

  Since:
    GemFire 3.0

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static java.util.List` | `existingSystems` The instances of `DistributedSystem` created in this VM.
    `protected static java.lang.Object` | `existingSystemsLock` This lock must be changed to add or remove a system.
    `static java.lang.String` | `PROPERTIES_FILE_DEFAULT` The default value of `PROPERTIES_FILE_PROPERTY` is `"gemfire.properties"`.
    `static java.lang.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 java.lang.String` | `PROPERTY_FILE` Deprecated. As of 9.0, please use `getPropertiesFile()` instead.
    `static java.lang.String` | `SECURITY_PROPERTIES_FILE_DEFAULT` The default value of `SECURITY_PROPERTIES_FILE_PROPERTY` is `"gfsecurity.properties"`.
    `static java.lang.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 java.lang.String` | `SECURITY_PROPERTY_FILE` Deprecated. As of 9.0, please use `getSecurityPropertiesFile()` instead.

    - ### Fields inherited from interface org.apache.geode.StatisticsTypeFactory

      `MAX_DESCRIPTORS_PER_TYPE`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DistributedSystem()` Creates a new instance of `DistributedSystem`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static void` | `addSystem(org.apache.geode.distributed.internal.InternalDistributedSystem newSystem)`
    `static DistributedSystem` | `connect(java.util.Properties config)` Deprecated. as of 6.5 use `CacheFactory.create(org.apache.geode.distributed.DistributedSystem)` or `ClientCacheFactory.create()` instead.
    `protected static DistributedSystem` | `connectForAdmin(java.util.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(java.lang.String name)` Find the distributed member with the given name
    `abstract java.util.Set<DistributedMember>` | `findDistributedMembers(java.net.InetAddress address)` Find the set of distributed members running on a given address
    `abstract java.util.Set<DistributedMember>` | `getAllOtherMembers()` Returns a set of all the other members in this distributed system.
    `abstract CancelCriterion` | `getCancelCriterion()`
    `abstract DistributedMember` | `getDistributedMember()` Returns the `DistributedMember` that identifies this connection to the distributed system.
    `abstract java.util.Set<DistributedMember>` | `getGroupMembers(java.lang.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()` Returns the `LogWriter` used for logging information.
    `abstract java.lang.String` | `getMemberId()` Deprecated. as of GemFire 5.0, use `getDistributedMember()` instead
    `abstract java.lang.String` | `getName()` Returns the name of this connection to the distributed system.
    `abstract java.util.Properties` | `getProperties()` Returns the configuration properties.
    `static java.lang.String` | `getPropertiesFile()` Returns the current value of `PROPERTIES_FILE_PROPERTY` system property if set or the default value `PROPERTIES_FILE_DEFAULT`.
    `static java.net.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 java.net.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()` Returns the `LogWriter` used for logging security related information.
    `abstract java.util.Properties` | `getSecurityProperties()` Returns the security specific configuration properties.
    `static java.lang.String` | `getSecurityPropertiesFile()` Returns the current value of `SECURITY_PROPERTIES_FILE_PROPERTY` system property if set or the default value `SECURITY_PROPERTIES_FILE_DEFAULT`.
    `static java.net.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 boolean` | `removeSystem(org.apache.geode.distributed.internal.InternalDistributedSystem oldSystem)`
    `protected static void` | `setEnableAdministrationOnly(boolean adminOnly)` see `AdminDistributedSystemFactory`
    `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, java.util.concurrent.TimeUnit units)` Wait for the DistributedSystem to finish reconnecting to the system and recreate the cache.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.apache.geode.StatisticsFactory

      `createAtomicStatistics, createAtomicStatistics, createAtomicStatistics, createStatistics, createStatistics, createStatistics, findStatisticsByNumericId, findStatisticsByTextId, findStatisticsByType`

    - ### Methods inherited from interface org.apache.geode.StatisticsTypeFactory

      `createDoubleCounter, createDoubleCounter, createDoubleGauge, createDoubleGauge, createIntCounter, createIntCounter, createIntGauge, createIntGauge, createLongCounter, createLongCounter, createLongGauge, createLongGauge, createType, createTypesFromXml, findType`

- - ### Field Detail

    - #### existingSystems

          protected static volatile java.util.List existingSystems

      The instances of `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`.

    - #### existingSystemsLock

          protected static final java.lang.Object existingSystemsLock

      This lock must be changed to add or remove a system. It is notified when a system is removed.
      See Also:
        `existingSystems`

    - #### PROPERTIES_FILE_PROPERTY

          public static final java.lang.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. Unless the value specifies the fully qualified path to the 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 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.

      Since:
        Geode 1.0
      See Also:
        `PROPERTIES_FILE_DEFAULT`, `getPropertiesFile()`, Constant Field Values

    - #### PROPERTIES_FILE_DEFAULT

          public static final java.lang.String PROPERTIES_FILE_DEFAULT

      The default value of `PROPERTIES_FILE_PROPERTY` is `"gemfire.properties"`. The location of the file will be resolved during connect as described for `PROPERTIES_FILE_PROPERTY`.
      Since:
        Geode 1.0
      See Also:
        `PROPERTIES_FILE_PROPERTY`, `getPropertiesFile()`, Constant Field Values

    - #### PROPERTY_FILE

          public static java.lang.String PROPERTY_FILE

      Deprecated. As of 9.0, please use `getPropertiesFile()` instead.
      The `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:
      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:
        GemFire 5.0
      See Also:
        `getPropertiesFile()`

    - #### SECURITY_PROPERTIES_FILE_PROPERTY

          public static final java.lang.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. Unless the value specifies the fully qualified path to the 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 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.

      Since:
        Geode 1.0
      See Also:
        `SECURITY_PROPERTIES_FILE_DEFAULT`, `getSecurityPropertiesFile()`, Constant Field Values

    - #### SECURITY_PROPERTIES_FILE_DEFAULT

          public static final java.lang.String SECURITY_PROPERTIES_FILE_DEFAULT

      The default value of `SECURITY_PROPERTIES_FILE_PROPERTY` is `"gfsecurity.properties"`. The location of the file will be resolved during connect as described for `SECURITY_PROPERTIES_FILE_PROPERTY`.
      Since:
        Geode 1.0
      See Also:
        `SECURITY_PROPERTIES_FILE_PROPERTY`, `getSecurityPropertiesFile()`, Constant Field Values

    - #### SECURITY_PROPERTY_FILE

          public static java.lang.String SECURITY_PROPERTY_FILE

      Deprecated. As of 9.0, please use `getSecurityPropertiesFile()` instead.
      The `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:
      1. the current directory
      2. the home directory
      3. the class path
      Only the first file found will be used.

      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.

      Since:
        GemFire 6.6.2
      See Also:
        `getSecurityPropertiesFile()`

  - ### Constructor Detail

    - #### DistributedSystem

          protected DistributedSystem()

      Creates a new instance of `DistributedSystem`. This constructor is protected so that it may only be invoked by subclasses.

  - ### Method Detail

    - #### connect

          public static DistributedSystem connect(java.util.Properties config)

      Deprecated. as of 6.5 use `CacheFactory.create(org.apache.geode.distributed.DistributedSystem)` or `ClientCacheFactory.create()` instead.
      Connects to a GemFire distributed system with a configuration supplemented by the given properties. See ConfigurationProperties for available GemFire properties and their meanings.

      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:
        `java.lang.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.
        `java.lang.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

    - #### addSystem

          protected static void addSystem(org.apache.geode.distributed.internal.InternalDistributedSystem newSystem)

    - #### removeSystem

          protected static boolean removeSystem(org.apache.geode.distributed.internal.InternalDistributedSystem oldSystem)

    - #### 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:
        GemFire 4.1

    - #### releaseThreadsSockets

          public static void releaseThreadsSockets()

      Frees up any socket resources owned by the calling thread.
      Since:
        GemFire 4.1

    - #### connectForAdmin

          protected static DistributedSystem connectForAdmin(java.util.Properties props)

      Returns a connection to the distributed system that is appropriate for administration. This method is for internal use only by the admin API.
      Since:
        GemFire 4.0

    - #### setEnableAdministrationOnly

          protected static void setEnableAdministrationOnly(boolean adminOnly)

      see `AdminDistributedSystemFactory`
      Since:
        GemFire 5.7

    - #### getLogWriter

          public abstract LogWriter getLogWriter()

      Returns the `LogWriter` used for logging information. See logFile.
      Throws:
        `java.lang.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:
        `java.lang.IllegalStateException` - This VM has disconnected from the distributed system.
      Since:
        GemFire 5.5

    - #### getProperties

          public abstract java.util.Properties getProperties()

      Returns the configuration properties.
      Returns:
        the configuration Properties

    - #### getSecurityProperties

          public abstract java.util.Properties getSecurityProperties()

      Returns the security specific configuration properties.
      Returns:
        the configuration Properties
      Since:
        GemFire 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 java.lang.String getMemberId()

      Deprecated. as of GemFire 5.0, use `getDistributedMember()` instead
      Returns a string that uniquely identifies this connection to the distributed system.
      Since:
        GemFire 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:
        GemFire 5.0

    - #### getAllOtherMembers

          public abstract java.util.Set<DistributedMember> getAllOtherMembers()

      Returns a set of all the other members in this distributed system.
      Returns:
        returns a set of all the other members in this distributed system.
      Since:
        GemFire 7.0

    - #### getGroupMembers

          public abstract java.util.Set<DistributedMember> getGroupMembers(java.lang.String group)

      Returns a set of all the members in the given group. Members join a group be setting the "groups" gemfire property.
      Returns:
        returns a set of all the member in a group.
      Since:
        GemFire 7.0

    - #### findDistributedMembers

          public abstract java.util.Set<DistributedMember> findDistributedMembers(java.net.InetAddress address)

      Find the set of distributed members running on a given address
      Returns:
        a set of all DistributedMembers that have any interfaces that match the given IP address. May be empty if there are no members.
      Since:
        GemFire 7.1

    - #### findDistributedMember

          public abstract DistributedMember findDistributedMember(java.lang.String name)

      Find the distributed member with the given name
      Returns:
        the distributed member that has the given name, or null if no member is currently running with the given name.
      Since:
        GemFire 7.1

    - #### getName

          public abstract java.lang.String getName()

      Returns the name of this connection to the distributed system.

    - #### getPropertiesFile

          public static java.lang.String getPropertiesFile()

      Returns the current value of `PROPERTIES_FILE_PROPERTY` system property if set or the default value `PROPERTIES_FILE_DEFAULT`.
      Since:
        Geode 1.0
      See Also:
        `PROPERTIES_FILE_PROPERTY`, `PROPERTIES_FILE_DEFAULT`

    - #### getSecurityPropertiesFile

          public static java.lang.String getSecurityPropertiesFile()

      Returns the current value of `SECURITY_PROPERTIES_FILE_PROPERTY` system property if set or the default value `SECURITY_PROPERTIES_FILE_DEFAULT`.
      Since:
        Geode 1.0
      See Also:
        `SECURITY_PROPERTIES_FILE_PROPERTY`, `SECURITY_PROPERTIES_FILE_DEFAULT`

    - #### getPropertiesFileURL

          public static java.net.URL getPropertiesFileURL()

      Gets an `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.

      Returns:
        a `URL` that names the GemFire property file. Null is returned if no property file was found.
      Since:
        Geode 1.0
      See Also:
        `PROPERTIES_FILE_PROPERTY`, `PROPERTIES_FILE_DEFAULT`, `getPropertiesFile()`

    - #### getPropertyFileURL

          public static java.net.URL getPropertyFileURL()

      Deprecated. As of 9.0, please use `getPropertiesFileURL()`
      Gets an `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.

      Returns:
        a `URL` that names the GemFire property file. Null is returned if no property file was found.
      Since:
        GemFire 5.0
      See Also:
        `getPropertiesFileURL()`

    - #### getSecurityPropertiesFileURL

          public static java.net.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.

      See `SECURITY_PROPERTIES_FILE_PROPERTY` for information on the name of the properties file and what locations it will be looked for in.

      Returns:
        a `URL` that names the GemFire security properties file. Null is returned if no properties file was found.
      Since:
        GemFire 6.6.2
      See Also:
        `SECURITY_PROPERTIES_FILE_PROPERTY`, `SECURITY_PROPERTIES_FILE_DEFAULT`, `getSecurityPropertiesFile()`

    - #### isReconnecting

          public 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.

      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.

      Returns:
        true if the DistributedSystem is attempting to reconnect or has finished reconnecting

    - #### waitUntilReconnected

          public abstract boolean waitUntilReconnected(long time,
                                                       java.util.concurrent.TimeUnit units)
                                                throws java.lang.InterruptedException

      Wait for the DistributedSystem to finish reconnecting to the system and recreate the cache.
      Parameters:
        `time` - amount of time to wait, or -1 to wait forever
        `units` -
      Returns:
        true if the system was reconnected
      Throws:
        `java.lang.InterruptedException` - if the thread is interrupted while waiting

    - #### stopReconnecting

          public abstract void stopReconnecting()

      Force the DistributedSystem to stop reconnecting. If the DistributedSystem is currently connected this will disconnect it and close the cache.

    - #### getReconnectedSystem

          public abstract DistributedSystem getReconnectedSystem()

      Returns the new DistributedSystem if there was an auto-reconnect