Package org.apache.geode.distributed

Class DistributedSystem

java.lang.Object
org.apache.geode.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(). 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.

Since:
GemFire 3.0

  • Field Details

    • existingSystems

      protected static volatile List<org.apache.geode.distributed.internal.InternalDistributedSystem> 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 Object existingSystemsLock
      This lock must be changed to add or remove a system. It is notified when a system is removed.
      See Also:

    • PROPERTIES_FILE_PROPERTY

      public static final 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

      public static final 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:

    • PROPERTY_FILE

      @Deprecated public static final 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:

    • SECURITY_PROPERTIES_FILE_PROPERTY

      public static final 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

      public static final 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_PROPERTY_FILE

      @Deprecated public static final 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:

  • Constructor Details

    • DistributedSystem

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

  • Method Details

    • connect

      @Deprecated public static DistributedSystem connect(Properties config)
      Deprecated.
      as of 6.5 use CacheFactory.create() 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
      Returns:
      a connection to the distributed system that is appropriate for administration
      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

    • addSystem

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

    • removeSystem

      protected static void 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

    • getConnection

      protected static DistributedSystem getConnection(Properties config)
      Returns an existing connection to the distributed system described by the given properties.
      Parameters:
      config - the properties used when creating a connection to the distributed system
      Returns:
      a connection to the distributed system that is appropriate for administration
      Since:
      GemFire 4.0

    • connectForAdmin

      protected static DistributedSystem connectForAdmin(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.
      Parameters:
      props - the properties used when creating a connection to the distributed system
      Returns:
      a connection to the distributed system that is appropriate for administration
      Since:
      GemFire 4.0

    • setEnableAdministrationOnly

      protected static void setEnableAdministrationOnly(boolean adminOnly)
      see AdminDistributedSystemFactory
      Parameters:
      adminOnly - whether this VM is dedicated to administration
      Since:
      GemFire 5.7

    • getLogWriter

      @Deprecated public abstract LogWriter getLogWriter()
      Deprecated.
      Returns the LogWriter used for logging information. See logFile.
      Returns:
      the LogWriter used for logging information
      Throws:
      IllegalStateException - This VM has disconnected from the distributed system.

    • getSecurityLogWriter

      @Deprecated public abstract LogWriter getSecurityLogWriter()
      Deprecated.
      Returns the LogWriter used for logging security related information. See logFile.
      Returns:
      the LogWriter used for logging security related information
      Throws:
      IllegalStateException - This VM has disconnected from the distributed system.
      Since:
      GemFire 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:
      GemFire 5.5

    • getCancelCriterion

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

    • disconnect

      @Deprecated 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.
      Returns:
      whether this DistributedSystem is connected to the distributed system
      See Also:

    • 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.
      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.
      Returns:
      a string that uniquely identifies this connection to the distributed system
      Since:
      GemFire 4.0
      See Also:

    • 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 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 Set<DistributedMember> getGroupMembers(String group)
      Returns a set of all the members in the given group. Members join a group by setting the "groups" gemfire property.
      Parameters:
      group - the group to which the distributed members to find belong
      Returns:
      returns a set of all the member in a group.
      Since:
      GemFire 7.0

    • findDistributedMembers

      public abstract Set<DistributedMember> findDistributedMembers(InetAddress address)
      Find the set of distributed members running on a given address
      Parameters:
      address - the address of the distributed members to find
      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(String name)
      Find the distributed member with the given name
      Parameters:
      name - the name of the distributed member to find
      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 String getName()
      Returns the name of this connection to the distributed system.
      Returns:
      the name of this connection to the distributed system

    • getPropertiesFile

      public static String getPropertiesFile()
      Returns the current value of PROPERTIES_FILE_PROPERTY system property if set or the default value PROPERTIES_FILE_DEFAULT.
      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:

    • getSecurityPropertiesFile

      public static String getSecurityPropertiesFile()
      Returns the current value of SECURITY_PROPERTIES_FILE_PROPERTY system property if set or the default value SECURITY_PROPERTIES_FILE_DEFAULT.
      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:

    • getPropertiesFileURL

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

      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:

    • getPropertyFileURL

      @Deprecated public static 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:

    • getSecurityPropertiesFileURL

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

      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:

    • 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, TimeUnit units) throws InterruptedException
      Wait for the DistributedSystem to finish reconnecting to the system and recreate the cache. This may throw a DistributedSystemDisconnectedException if reconnect fails. The exception will detail what went wrong.
      Parameters:
      time - amount of time to wait, or -1 to wait forever
      units - the units associated with the time
      Returns:
      true if the system was reconnected
      Throws:
      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
      Returns:
      the new DistributedSystem if there was an auto-reconnect