Introduction

Geode’s Locator process is an extendable collection of location services.

When you start a cache server process it will contact all locators in order to find the cluster’s membership coordinator so that it can join the distributed system.  This uses the peer-location service in the Locator.

When a client cache is started its connection Pool will contact locators in order to find a cache server to use. This uses the server-location service in the Locator.

When a cluster has WAN replication enabled the locators will exchange information with remote sites so that the replication mechanisms in the cluster’s servers can find remote endpoints.  This uses the WAN-location service in the Locator

The Locator also hosts the cluster configuration service that servers will use to construct their caches.  This service uses a disk store to persist the configuration.

Locators are started with the Gfsh command-line program.  You can also start a Locator using the org.apache.geode.distributed.Locator API or the org.apache.geode.distributed.LocatorLauncher Java program.  All of these mechanisms use the class InternalLocator to actually boot up the Locator and its services.

> Gfsh start-locator --name=clusterLocator1

Communicating with a Locator

Both clients and servers use the class TcpClient to communicate with a Locator.  Inside the locator the class TcpServer is responsible for accepting TCP/IP connections from other processes, reading a request, responding to the request and closing the TCP/IP connection.

TcpClient uses DataSerializer to serialize messages sent to the Locator and to deserialize responses received from the Locator.  TcpClient is also careful to abort the TCP/IP connection it formed with the Locator so that the Locator doesn’t accumulate sockets in a TIME_WAIT state, which could cause the Locator to run out of file handles.

TcpClient myClient = new TcpClient();

final String serverGroup = "";

GetAllServersRequest request = new GetAllServersRequest(serverGroup);

final int timeout = 60000; // milliseconds

final boolean expectResponse = true;

GetAllServersResponse response = (GetAllServersResponse)myClient.requestToServer(locatorInetSocketAddress, request, timeout, expectResponse);

Locator Handlers

TcpServer holds a PrimaryHandler that processes most messages, though its processing of them mostly entails handing them off to delegate Handlers (the actual interface is TcpHandler).  There are different handlers for each service hosted by the Locator.

Peer location

Peer location is implemented by the “handler” class GMSLocator.  You can find a detailed examination of how this class is used here:

https://cwiki.apache.org/confluence/display/GEODE/GMSJoinLeave+message+sequence+diagrams

Server location

Clients make use of the server-location service, which is implemented by the “handler” class ServerLocator.  This handler caches information about servers such as their TCP/IP addresses and their current load.  It also knows about what other locators are available so that clients can contact one locator and use it to discover the other locators in the cluster.

WAN location

Locators that are configured to know about one or more “remote” locators will attempt to contact those locators and find out about other locators in the remote cluster. This information is then handed out to servers in the cluster, via TcpClient, that host WAN transmitters so that they can configure the WAN connection pool to communicate with the remote cluster.

There is no Handler for this service – instead any message that isn’t consumed by another handler is given to this class to process. This is hard-coded into PrimaryHandler.processRequest.  I think this is a minor bug – this service should have a Handler like the other services in order to keep the architecture of the Locator uniform.

Adding a new handler

A new message handler can easily be added to the Locator.  Your new handler needs to implement TcpHandler and in its processRequest() method it needs to process any message it’s been registered to handle.  You register these messages with the PrimaryHandler using the addHandler(messageClass, handlerInstance) method.

The handler must process each message it’s asked to handle and return a DataSerializableFixedID result to send back to the requesting process.

Adding a new message

A new message can be added by registering it and its handler with the PrimaryHandler using the above method. 

All messages (whether request or response) must implement DataSerializableFixedID so that they can be serialized without the overhead of registering them as regular DataSerializable objects.  All Geode processes know how to serialize and deserialize DataSerializableFixedID objects.

Existing handlers and messages aren’t very object-oriented in that the messages are pretty much just data structures with little behavior.  Switch statements in the handlers are used to branch off to code that provides the behavior for each message.  You don't need to follow that pattern when implementing new handlers.

Cluster configuration service

The cluster configuration service requires the Locator to host a Cache.  This Cache is used to create a configuration Region in which the service stores most cluster configuration information.  This Region has a disk store that persists the configuration information so that it can be recovered if the locator should be stopped and restarted.

Deployed JAR files are held outside of the Cache.  These are, instead, held in the file system and a path to them is stored in the Cache.

When a new server is started it uses TcpClient to request the cluster configuration from locators hosting a Cluster Configuration service.  This is handled by a ConfigurationRequestHandler in the Locator.

What’s the locatorView.dat file?

Aside from the cluster configuration the Locator also has another persistent store, its persistent membership view file.  This file is used to find members in the cluster if the locator is stopped and restarted.  If this file is lost a restarted locator won’t be able to join the cluster unless a locator already exists in the cluster.

Each time a server joins or leaves the cluster a new membership view is sent around the cluster and the locators will store it in their persistent membership view file.  When a locator restarts it will try to recover this information from another locator and, failing to do that, it will recover the view from this file.