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

```
public abstract class Locator
extends java.lang.Object
```
Represents a distribution locator server that provides discovery information to members and clients of a GemFire distributed system. In most GemFire distributed cache architectures, distribution locators are run in their own process. A stand-alone locator process is managed using gfsh command line utility. The stand-alone locator configuration provides high-availability of membership information.
This class allows a GemFire application VM to host a distribution locator. Such a configuration minimizes the number of processes that are required to run GemFire. However, hosting distribution locators is not generally recommended because if the application VM exits it would not be possible for new applications to connect to the distributed system until it is restarted.
Locators persist membership information in a locatorXXXview.dat file. This file is used to recover information about the cluster when a locator starts if there are no other currently running locators. It allows the restarted locator to rejoin the cluster.
NOTE: In this release of the product locators log membership views and cache server status in a locatorXXXviews.log file, where XXX is the locator's port. This is a rolling log capped in size at 5mb. In order to log cache server status the locator will enable server-location, so the locator must be started with a DistributedSystem or be started so that it creates a DistributedSystem. This means that it is not possible in this release to use APIs to start a locator and then start a DistributedSystem.

Since:

GemFire 4.0

Field Summary

Fields
Modifier and Type	Field	Description
`protected java.net.InetAddress`	`bindAddress`	no longer used but kept for binary compatibility
`protected org.apache.geode.distributed.internal.tcpserver.HostAddress`	`hostAddress`	The bind address for this locator
`protected java.lang.String`	`hostnameForClients`	the hostname to give to clients so they can connect to this locator.
`protected java.io.File`	`logFile`	The file to which this locator logs

Constructor Summary

Constructors
Constructor Description

Locator()

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`java.lang.String`	`asString()`	Get the string representation of this `Locator` in host[port] format.
`java.net.InetAddress`	`getBindAddress()`	Returns the IP address to which this locator's listening socket is bound.
`abstract DistributedSystem`	`getDistributedSystem()`	Returns the distributed system started by this locator, if any
`java.lang.String`	`getHostnameForClients()`	Returns the hostname that will be given to clients so that they can connect to this locator.
`static Locator`	`getLocator()`	Returns the locator if it exists in this JVM.
`static java.util.List<Locator>`	`getLocators()`	Deprecated. as of 7.0 use `getLocator()` instead
`java.io.File`	`getLogFile()`	Returns the log file to which this locator's output is written
`abstract java.lang.Integer`	`getPort()`	Returns the port on which this locator runs
`static boolean`	`hasLocator()`	Returns true if a locator exists in this JVM.
`static boolean`	`hasLocators()`	Deprecated. as of 7.0 use `hasLocator()` instead.
`abstract boolean`	`isPeerLocator()`	Indicates whether the locator provides peer location services to members
`abstract boolean`	`isServerLocator()`	Indicates whether the locator provides server location services to clients
`static Locator`	`startLocator(int port, java.io.File logFile)`	Deprecated. as of 7.0 use startLocatorAndDS instead.
`static Locator`	`startLocator(int port, java.io.File logFile, java.net.InetAddress bindAddress)`	Deprecated. as of 7.0 use startLocatorAndDS instead.
`static Locator`	`startLocatorAndDS(int port, java.io.File logFile, java.net.InetAddress bindAddress, java.util.Properties dsProperties)`	Starts a new distribution locator host by this VM that binds to the given network address.
`static Locator`	`startLocatorAndDS(int port, java.io.File logFile, java.net.InetAddress bindAddress, java.util.Properties dsProperties, boolean peerLocator, boolean serverLocator, java.lang.String hostnameForClients)`	Deprecated. use a different startup method peerLocator and serverLocator parameters are ignored
`static Locator`	`startLocatorAndDS(int port, java.io.File logFile, java.util.Properties distributedSystemProperties)`	Starts a new distribution locator host by this VM, and an admin distributed system controlled by the locator.
`abstract void`	`stop()`	Stops this distribution locator.
`java.lang.String`	`toString()`	Returns a brief description of this `Locator`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - logFile
```
protected java.io.File logFile
```
    The file to which this locator logs
  - bindAddress
```
protected java.net.InetAddress bindAddress
```
    no longer used but kept for binary compatibility
  - hostAddress
```
protected org.apache.geode.distributed.internal.tcpserver.HostAddress hostAddress
```
    The bind address for this locator
  - hostnameForClients
```
protected java.lang.String hostnameForClients
```
    the hostname to give to clients so they can connect to this locator.
    
    Since:
    
    GemFire 5.7
- Constructor Detail
  - Locator
```
public Locator()
```
- Method Detail
  - startLocator
```
@Deprecated
public static Locator startLocator(int port,
                                   java.io.File logFile)
                            throws java.io.IOException
```
    Deprecated.
    as of 7.0 use startLocatorAndDS instead.
    
    Starts a new distribution locator host by this VM. The locator's listening sockets will bind to all network addresses. The locator will look for a gemfire.properties file, or equivalent system properties to fill in the gaps in its configuration. If you are using multicast communications, the locator should be configured with the same settings that your applications will use.
    The locator will not start a distributed system. The locator will provide peer location services only.
    
    Parameters:
    
    port - The port on which the locator will listen for membership information requests from new members
    
    logFile - The file to which the locator logs information. The directory that contains the log file is used as the output directory of the locator (see -dir option to the gemfire command).
    
    Returns:
    
    the newly started locator
    
    Throws:
    
    java.lang.IllegalArgumentException - If port is not in the range 0 to 65536
    
    SystemIsRunningException - If another locator is already running in outputDir
    
    GemFireIOException - If the directory containing the logFile does not exist or cannot be written to
    
    java.io.IOException - If the locator cannot be started
  - startLocatorAndDS
```
public static Locator startLocatorAndDS(int port,
                                        java.io.File logFile,
                                        java.util.Properties distributedSystemProperties)
                                 throws java.io.IOException
```
    Starts a new distribution locator host by this VM, and an admin distributed system controlled by the locator. The locator's listening sockets will bind to all network addresses. The locator will use the given properties to start an AdminDistributedSystem.
    The locator starts a AdminDistributedSystem configured with the given properties to provide the system with a long-running process that can be relied on for stable membership information. The locator will provide provide peer and cache server location services.
    
    Parameters:
    
    port - The port on which the locator will listen for membership information requests from new members
    
    logFile - The file to which the locator logs information. The directory that contains the log file is used as the output directory of the locator (see -dir option to the gemfire command).
    
    distributedSystemProperties - The properties used to configure the locator's distributed system. If there are multiple locators in the system, this should note them in the "locators" setting. If The distributed system is using multicast, the "mcast-port" should also be set.
    
    Returns:
    
    the newly started locator
    
    Throws:
    
    java.lang.IllegalArgumentException - If port is not in the range 0 to 65536
    
    SystemIsRunningException - If another locator is already running in outputDir
    
    GemFireIOException - If the directory containing the logFile does not exist or cannot be written to
    
    java.io.IOException - If the locator cannot be started
    
    Since:
    
    GemFire 5.0
  - startLocator
```
@Deprecated
public static Locator startLocator(int port,
                                   java.io.File logFile,
                                   java.net.InetAddress bindAddress)
                            throws java.io.IOException
```
    Deprecated.
    as of 7.0 use startLocatorAndDS instead.
    
    Starts a new distribution locator host by this VM. The locator will look for a gemfire.properties file, or equivalent system properties to fill in the gaps in its configuration.
    The locator will not start a distributed system. The locator will provide peer location services only.
    
    Parameters:
    
    port - The port on which the locator will listen for membership information requests from new members
    
    logFile - The file to which the locator logs information. The directory that contains the log file is used as the output directory of the locator (see -dir option to the gemfire command).
    
    bindAddress - The IP address to which the locator's socket binds
    
    Returns:
    
    the newly started locator
    
    Throws:
    
    java.lang.IllegalArgumentException - If port is not in the range 0 to 65536
    
    SystemIsRunningException - If another locator is already running in outputDir
    
    GemFireIOException - If the directory containing the logFile does not exist or cannot be written to
    
    java.io.IOException - If the locator cannot be started
  - startLocatorAndDS
```
public static Locator startLocatorAndDS(int port,
                                        java.io.File logFile,
                                        java.net.InetAddress bindAddress,
                                        java.util.Properties dsProperties)
                                 throws java.io.IOException
```
    Starts a new distribution locator host by this VM that binds to the given network address.
    The locator starts a AdminDistributedSystem configured with the given properties to provide the system with a long-running process that can be relied on for stable membership information. The locator will provide peer and cache server location services.
    
    Parameters:
    
    port - The port on which the locator will listen for membership information requests from new members
    
    logFile - The file to which the locator logs information. The directory that contains the log file is used as the output directory of the locator (see -dir option to the gemfire command).
    
    bindAddress - The IP address to which the locator's socket binds
    
    dsProperties - The properties used to configure the locator's DistributedSystem. If there are multiple locators, the "locators" property should be set. If multicast is being used, the "mcast-port" property should be set.
    
    Returns:
    
    the newly started locator
    
    Throws:
    
    java.lang.IllegalArgumentException - If port is not in the range 0 to 65536
    
    SystemIsRunningException - If another locator is already running in outputDir
    
    GemFireIOException - If the directory containing the logFile does not exist or cannot be written to
    
    java.io.IOException - If the locator cannot be started
    
    Since:
    
    GemFire 5.0
  - startLocatorAndDS
```
@Deprecated
public static Locator startLocatorAndDS(int port,
                                        java.io.File logFile,
                                        java.net.InetAddress bindAddress,
                                        java.util.Properties dsProperties,
                                        boolean peerLocator,
                                        boolean serverLocator,
                                        java.lang.String hostnameForClients)
                                 throws java.io.IOException
```
    Deprecated.
    use a different startup method peerLocator and serverLocator parameters are ignored
    
    Starts a new distribution locator host by this VM that binds to the given network address.
    The locator starts a AdminDistributedSystem configured with the given properties to provide the system with a long-running process that can be relied on for stable membership information. The locator will provide provide peer and cache server location services.
    
    Parameters:
    
    port - The port on which the locator will listen for membership information requests from new members
    
    logFile - The file to which the locator logs information. The directory that contains the log file is used as the output directory of the locator (see -dir option to the gemfire command).
    
    bindAddress - The IP address to which the locator's socket binds
    
    dsProperties - The properties used to configure the locator's DistributedSystem. If there are multiple locators, the "locators" property should be set. If multicast is being used, the "mcast-port" property should be set.
    
    peerLocator - True if the locator should provide membership information to peers in the distributed system.
    
    serverLocator - True if the locator should provide information about cache servers to clients connecting to the distributed system.
    
    hostnameForClients - the name to give to clients for connecting to this locator
    
    Returns:
    
    the newly started locator
    
    Throws:
    
    java.lang.IllegalArgumentException - If port is not in the range 0 to 65536 or peerLocator and serverLocator are both false.
    
    SystemIsRunningException - If another locator is already running in outputDir
    
    GemFireIOException - If the directory containing the logFile does not exist or cannot be written to
    
    java.io.IOException - If the locator cannot be started
    
    Since:
    
    GemFire 5.7, GemFire 5.7
  - getLocators
```
@Deprecated
public static java.util.List<Locator> getLocators()
```
    Deprecated.
    as of 7.0 use getLocator() instead
    
    Returns an unmodifiable List of all of the Locators that are hosted by this VM.
    
    Returns:
    
    an unmodifiable List of all of the Locators that are hosted by this VM
  - getLocator
```
public static Locator getLocator()
```
    Returns the locator if it exists in this JVM. Otherwise returns null.
    
    Returns:
    
    the locator that exists in this JVM; null if no locator.
    
    Since:
    
    GemFire 7.0
  - hasLocators
```
@Deprecated
public static boolean hasLocators()
```
    Deprecated.
    as of 7.0 use hasLocator() instead.
    
    Examine the size of the collection of locators running in this VM
    
    Returns:
    
    the number of locators running in this VM
  - hasLocator
```
public static boolean hasLocator()
```
    Returns true if a locator exists in this JVM.
    
    Returns:
    
    true if a locator exists in this JVM.
    
    Since:
    
    GemFire 7.0
  - getPort
```
public abstract java.lang.Integer getPort()
```
    Returns the port on which this locator runs
    
    Returns:
    
    the port on which this locator runs
  - getDistributedSystem
```
public abstract DistributedSystem getDistributedSystem()
```
    Returns the distributed system started by this locator, if any
    
    Returns:
    
    the distributed system started by this locator, if any
  - getLogFile
```
public java.io.File getLogFile()
```
    Returns the log file to which this locator's output is written
    
    Returns:
    
    the log file to which this locator's output is written
  - getBindAddress
```
public java.net.InetAddress getBindAddress()
```
    Returns the IP address to which this locator's listening socket is bound.
    
    Returns:
    
    the IP address to which this locator's listening socket is bound
  - getHostnameForClients
```
public java.lang.String getHostnameForClients()
```
    Returns the hostname that will be given to clients so that they can connect to this locator. Returns null if clients should use the bind address.
    
    Returns:
    
    the hostname that will be given to clients so that they can connect to this locator
    
    Since:
    
    GemFire 5.7
  - isPeerLocator
```
public abstract boolean isPeerLocator()
```
    Indicates whether the locator provides peer location services to members
    
    Returns:
    
    if peer location is enabled
  - isServerLocator
```
public abstract boolean isServerLocator()
```
    Indicates whether the locator provides server location services to clients
    
    Returns:
    
    if server location is enabled
  - stop
```
public abstract void stop()
```
    Stops this distribution locator.
  - toString
```
public java.lang.String toString()
```
    Returns a brief description of this Locator
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a brief description of this Locator
  - asString
```
public java.lang.String asString()
```
    Get the string representation of this Locator in host[port] format.
    
    Returns:
    
    the string representation of this Locator in host[port] format

Gemfire JavaDocs_test

Class Locator

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

logFile

bindAddress

hostAddress

hostnameForClients

Constructor Detail

Locator

Method Detail

startLocator

startLocatorAndDS

startLocator

startLocatorAndDS

startLocatorAndDS

getLocators

getLocator

hasLocators

hasLocator

getPort

getDistributedSystem

getLogFile

getBindAddress

getHostnameForClients

isPeerLocator

isServerLocator

stop

toString

asString