Pivotal GemFire Locator Process

The locator is a Pivotal GemFire process that tells new, connecting members where running members are located and provides load balancing for server use.

You can run locators as peer locators, server locators, or both:
  • Peer locators give joining members connection information to members already running in the locator's distributed system.
  • Server locators give clients connection information to servers running in the locator's distributed system. Server locators also monitor server load and send clients to least-loaded servers.

By default, locators run as peer and server locators.

You can run the locator standalone or co-located inside another GemFire process. Running your locators standalone provides the highest reliability and availability of the locator service as a whole.

You must have tools.jar (included with the JDK) added to your CLASSPATH in order to manage servers using either gfsh or the LocatorLauncher API.

Locator Configuration and Log Files

Locator configuration and log files have the following properties:
  • Locators are members of the distributed system just like any other member. In terms of mcast-port and locators configuration, a locator should be configured in the same manner as a server. Therefore, if there are two locators in the distributed system, each locator should reference both locators (just like a server member would).
  • You can configure locators by using gemfire.properties or by specifying start-up parameters on the command line. If you are specifying the locator's configuration in a properties file, locators require the same gemfire.properties settings as other members of the distributed system and the same gfsecurity.properties settings if you are using a separate, restricted access security settings file.
    For example, to configure both locators and a multicast port in gemfire.properties:
    locators=host1[port1],host2[port2]
    mcast-port=0
    The same configuration on the gfsh command line:
    gfsh>start locator --name=locator1
  • There is no cache configuration specific to locators.
  • For logging output, the locator creates a log file in its current working directory. Log file output defaults to locator_name.log in the locator's working directory. If you restart a locator with a previously used locator name, the existing locator_name.log file is automatically renamed for you (for example, locator1-01-01.log or locator1-02-01.log). You can modify the level of logging details in this file by specifying a level in the --log-level argument when starting up the locator.
  • By default, the Locator will start in a subdirectory (named after the Locator) under the directory where gfsh is executed. This subdirectory is considered the current working directory. You can also specify a different working directory when starting the Locator in gfsh.

Start the Locator

Use the following steps to guidelines to start the locator:
  • Standalone locator. Start a standalone locator in one of these ways:
    • Use the gfsh command-line utility. See Using the GemFire SHell (gfsh) for more information on using gfsh. The syntax for starting the

      Example commands:

      gfsh>start locator --name=locator1
      
      gfsh> start locator --name=locator2 --bind-address=192.168.129.205 --port=13489
      
    • Start the locator using the main method in the com.gemstone.gemfire.distributed.LocatorLauncher class and the Java executable. For example:
      working/directory/of/Locator/process$java -server -classpath "$GEMFIRE/lib/gemfire.jar:$GEMFIRE/lib/antlr.jar:$GEMFIRE/lib/commons-io-2.3.jar:\
      $GEMFIRE/lib/commons-logging.jar:$GEMFIRE/lib/jackson-core-asl-1.9.9.jar:$GEMFIRE/lib/jansi-1.8.jar:/$GEMFIRE/lib/jline-1.0.S2-B.jar:\
      $GEMFIRE/lib/spring-asm-3.1.1.RELEASE.jar:$GEMFIRE/lib/spring-core-3.1.1.RELEASE.jar:$GEMFIRE/lib/spring-shell-1.0.0.jar:\
      $GEMFIRE/lib/tomcat-embed-core.jar:$GEMFIRE/lib/tomcat-embed-jasper.jar:$GEMFIRE/lib/tomcat-embed-logging-juli.jar:/path/to/your/application/classes.jar" \
      com.gemstone.gemfire.distributed.LocatorLauncher start Locator1 --port=11235 --redirect-output

      Specifically, you use the LocatorLauncher class API to run an embedded Locator service in Java application processes that you have created. The directory where you execute the java command becomes the working directory for the locator process.

    • When starting up multiple locators, do not start them up in parallel (in other words, simultaneously). As a best practice, you should wait approximately 30 seconds for the first locator to complete startup before starting any other locators. To check the successful startup of a locator, check for locator log files. To view the uptime of a running locator, you can use the gfsh status locator command.
  • Co-located locator. Manage a co-located locator at member startup or through the APIs:
    • Use the gemfire.properties start-locator setting to start the locator automatically inside your GemFire member. See gemfire.properties and gfsecurity.properties (GemFire Properties). The locator stops automatically when the member exits. The property has the following syntax:
      #gemfire.properties
      start-locator=[address]port[,server={true|false},peer={true|false}] 

      Example:

      #gemfire.properties
      start-locator=13489
    • Use com.gemstone.gemfire.distributed.LocatorLauncher API to start the locator inside your code. Use the LocatorLauncher.Builder class to construct an instance of the LocatorLauncher, and then use the start() method to start a Locator service embedded in your Java application process. The other methods in the LocatorLauncher class provide status information about the locator and allow you to stop the locator.
      import com.gemstone.gemfire.distributed.LocatorLauncher;
      
       public class MyEmbeddedLocator {
      
          public static void main(String[] args){
              LocatorLauncher locatorLauncher  = new LocatorLauncher.Builder()
                .setMemberName("locator1")
                .setPort(13489)
                .build();
      
                locatorLauncher.start();  
      
                System.out.println("Locator successfully started");
              }
          }
      Here's another example that embeds the locator within an application, starts it and then checks the status of the locator before allowing other members to access it:
      package example;
      
      import ...
      
      class MyApplication implements Runnable {
      
        private final LocatorLauncher locatorLauncher;
        
        public MyApplication(final String... args) {
          validateArgs(args);
      
          locatorLauncher = new LocatorLauncher.Builder()
            .setMemberName(args[0])
            .setPort(Integer.parseInt(args[1])
            .setRedirectOutput(true)
            .build();
        }
      
        protected void args(final String[] args) {
          ...
        }
      
        public void run() {
          ...
      
          // start the GemFire Locator in-process
          locatorLauncher.start();
      
          // wait for Locator to start and be ready to accept member (client) connections
          locatorLauncher.waitOnStatusResponse(30, 5, TimeUnit.SECONDS);
      
          ...
        }
      
        public static void main(final String... args) {
          new MyApplication(args).run();
        }
      
      }
      Then to execute the application, you would run:
      /working/directory/of/MyApplication$ java -server -classpath "$GEMFIRE/lib/locator-dependencies.jar:/path/to/application/classes.jar" example.MyApplication Locator1 11235
      The directory where you execute the java command becomes the working directory for the locator process.

Check Locator Status

If you are connected to the distributed system in gfsh, you can check the status of a running Locator by providing the Locator name. For example:
gfsh>status locator --name=locator1
If you are not connected to a distributed system, you can check the status of a local Locator by providing the process ID, the Locator's hostname and port, or the Locator's current working directory. For example:
gfsh>status locator --pid=2986
or
gfsh>status locator --host=host1 --port=1035
or
gfsh>status locator --dir=<locator_working_directory>
where <locator_working_directory> corresponds to the local working directory where the locator is running.
If successful, the command returns the following information (with the JVM arguments that were provided at startup):
gfsh>status locator --dir=locator1
Locator in C:\PivotalGemFire70\Latest\locator1 on GemFireStymon[10334] as locator1 
is currently online.
Process ID: 3336
Uptime: 2 hours 15 seconds
GemFire Version: 7.0
Java Version: 1.6.0_26
Log File: C:\PivotalGemFire70\Latest\locator1\locator1.log
JVM Arguments:
...

Stop the Locator

If you are connected to the distributed system in gfsh, you can stop a running locator by providing the locator name. For example:
gfsh>stop locator --name=locator1
If you are not connected to a distributed system, you can stop a local locator by specifying the locator's process ID or the locator's current working directory. For example:
gfsh>stop locator --pid=2986
or
gfsh>stop locator --dir=<locator_working_directory>
where <locator_working_directory> corresponds to the local working directory where the locator is running.