GemFire 6.6.4

com.gemstone.gemfire.distributed
Class Locator

java.lang.Object
  extended by com.gemstone.gemfire.distributed.Locator

public abstract class Locator
extends 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 administration API or the gemfire command line utility:

 $ gemfire start-locator
 
The stand-alone locator configuration provides high-availability of the 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, the primary membership list for the distributed system would be lost and it would not be possible for new applications to connect to the distributed system.

It is important to remember that an application that hosts a distribution locator must start its locator before it (or any other potential member) connects to the distributed system.

Since:
4.0

Constructor Summary
Locator()
           
 
Method Summary
 String asString()
          Get the string representation of this Locator in host[port] format.
 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
 String getHostnameForClients()
          Returns the hostname that will be given to clients so that they can connect to this locator.
static List<Locator> getLocators()
          Returns an unmodifiable List of all of the Locators that are hosted by this VM.
 File getLogFile()
          Returns the log file to which this locator's output is written
 int getPort()
          Returns the port on which this locator runs
static boolean hasLocators()
          Examine the size of the collection of locators running in this VM
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 void main(String[] args)
          Starts a distribution locator from the command line.
static Locator startLocator(int port, File logFile)
          Starts a new distribution locator host by this VM.
static Locator startLocator(int port, File logFile, InetAddress bindAddress)
          Starts a new distribution locator host by this VM.
static Locator startLocatorAndDS(int port, File logFile, InetAddress bindAddress, Properties dsProperties)
          Starts a new distribution locator host by this VM that binds to the given network address.
static Locator startLocatorAndDS(int port, File logFile, InetAddress bindAddress, Properties dsProperties, boolean peerLocator, boolean serverLocator, String hostnameForClients)
          Starts a new distribution locator host by this VM that binds to the given network address.
static Locator startLocatorAndDS(int port, File logFile, 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.
 String toString()
          Returns a brief description of this Locator
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Locator

public Locator()
Method Detail

startLocator

public static Locator startLocator(int port,
                                   File logFile)
                            throws IOException
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).
Throws:
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
IOException - If the locator cannot be started

startLocatorAndDS

public static Locator startLocatorAndDS(int port,
                                        File logFile,
                                        Properties distributedSystemProperties)
                                 throws 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.
Throws:
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
IOException - If the locator cannot be started
Since:
5.0

startLocator

public static Locator startLocator(int port,
                                   File logFile,
                                   InetAddress bindAddress)
                            throws IOException
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 provice 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
Throws:
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
IOException - If the locator cannot be started

startLocatorAndDS

public static Locator startLocatorAndDS(int port,
                                        File logFile,
                                        InetAddress bindAddress,
                                        Properties dsProperties)
                                 throws 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 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.
Throws:
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
IOException - If the locator cannot be started
Since:
5.0

startLocatorAndDS

public static Locator startLocatorAndDS(int port,
                                        File logFile,
                                        InetAddress bindAddress,
                                        Properties dsProperties,
                                        boolean peerLocator,
                                        boolean serverLocator,
                                        String hostnameForClients)
                                 throws 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 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
Throws:
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
IOException - If the locator cannot be started
Since:
5.7, 5.7

getLocators

public static List<Locator> getLocators()
Returns an unmodifiable List of all of the Locators that are hosted by this VM.


hasLocators

public static boolean hasLocators()
Examine the size of the collection of locators running in this VM

Returns:
the number of locators running in this VM

getPort

public int getPort()
Returns the port on which this locator runs


getDistributedSystem

public abstract DistributedSystem getDistributedSystem()
Returns the distributed system started by this locator, if any


getLogFile

public File getLogFile()
Returns the log file to which this locator's output is written


getBindAddress

public InetAddress getBindAddress()
Returns the IP address to which this locator's listening socket is bound.


getHostnameForClients

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

Since:
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 String toString()
Returns a brief description of this Locator

Overrides:
toString in class Object

asString

public String asString()
Get the string representation of this Locator in host[port] format.


main

public static void main(String[] args)
Starts a distribution locator from the command line.

This method of starting the locator is provided as an alternative to the gemfire start-locator command to give you complete control over the java virtual machine's configuration.

The gemfire stop-locator command can be used to stop a locator that is started with this class.

java com.gemstone.gemfire.distributed.Locator port [bind-address] [gemfire-properties-file] [peer] [server]

port - the tcp/ip port that the locator should listen on. This is the port number that applications will refer to in their locators property in gemfire.properties

bind-address - the tcp/ip address that the locator should bind to. This can be missing or be an empty string, which causes the locator to listen on all host addresses.

gemfire-properties-file - the location of a gemfire.properties file to be used in configuring the locator's distributed system. This can be missing or be an empty string, which will cause the locator to use the default search for gemfire.properties.

peer - true to start the peer locator service, false to disable it. If unspecified, default to true.

server - true to start the cache server locator service, false to disable it. If unspecified, defaults to true.

hostname-for-clients - the ip address or host name that clients will be told to use to connect to this locator. If unspecified, defaults to the bind-address.

Since:
5.0

GemFire 6.6.4

Copyright © 1997-2012 VMware, Inc. All rights reserved.