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 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(). 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 Detail

      • existingSystems

        protected static volatile java.util.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 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

      • PROPERTY_FILE

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

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

        @Deprecated
public static DistributedSystem connect​(java.util.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:
        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 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​(java.util.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​(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.
        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:
        java.lang.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:
        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

        @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:
        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.
        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.
        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 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 java.util.Set<DistributedMember> findDistributedMembers​(java.net.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​(java.lang.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 java.lang.String getName()
        Returns the name of this connection to the distributed system.
        Returns:
        the name of this connection to the distributed system

      • 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

        @Deprecated
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()

      • 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. 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:
        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
        Returns:
        the new DistributedSystem if there was an auto-reconnect