LocatorLauncher.Builder
Following the Builder design pattern, the LocatorLauncher Builder is used to configure and create a properly
initialized instance of the LocatorLauncher class for running the Locator and performing other Locator
operations.

start()
Starts a Locator running on the specified port and bind address, as determined by getPort and getBindAddress
respectively, defaulting to 10334 and 'localhost' if not specified, with both peer and server location enabled.

isForcing

Determines whether the PID file is allowed to be overwritten when the Locator is started and a PID file
already exists in the Locator's specified working directory.

Returns:

boolean indicating if force has been enabled.

isHelping

public boolean isHelping()

Determines whether this launcher will be used to display help information. If so, then none of the standard
Locator launcher commands will be used to affect the state of the Locator. A launcher is said to be 'helping'
if the user entered the "--help" option (switch) on the command-line.

Returns:

a boolean value indicating if this launcher is used for displaying help information.

run

public void run()

The Runnable method used to launch the Locator with the specified command. If 'start' has been issued, then run
will block as expected for the Locator to stop. The 'start' command is implemented with a call to start()
followed by a call to waitOnLocator().

start

Starts a Locator running on the specified port and bind address, as determined by getPort and getBindAddress
respectively, defaulting to 10334 and 'localhost' if not specified, with both peer and server location enabled.
'start' is an asynchronous invocation of the Locator. As such, this method makes no guarantees whether the
Locator's location services (peer and server) are actually running before it returns. The Locator's
location-based services are initiated in separate, daemon Threads and depends on the relative timing
and scheduling of those Threads by the JVM. If the application using this API wishes for the Locator to continue
running after normal application processing completes, then one must call waitOnLocator.
Given the nature of start, the Locator's status will be in either 1 of 2 possible states. If the 'request' to
start the Locator proceeds without exception, the status will be 'STARTED'. However, if any exception is
encountered during the normal startup sequence, then a RuntimeException is thrown and the status is set to
'STOPPED'.

waitOnStatusResponse

Waits for a Locator status request response to be returned up to the specified timeout in the given unit of time.
This call will send status requests at fixed intervals in the given unit of time until the timeout expires. If
the request to determine the Locator's status is successful, then the Locator is considered to be 'ONLINE'.
Otherwise, the Locator is considered to be unresponsive to the status request.
However, this does not necessarily imply the Locator start was unsuccessful, only that a response was not received
in the given time period.
Note, this method does not block or cause the Locator's location-based services (daemon Threads) to continue
running in anyway if the main application Thread terminates when running the Locator in-process. If the caller
wishes to start a Locator in an asynchronous manner within the application process, then a call should be made to
waitOnLocator.

Parameters:

timeout - a long value in time unit indicating when the period of time should expire in attempting
to determine the Locator's status.

interval - a long value in time unit for how frequent the requests should be sent to the Locator.

timeUnit - the unit of time in which the timeout and interval are measured.

Returns:

the state of the Locator, which will either be 'ONLINE' or "NOT RESPONDING'. If the status returned is
'NOT RESPONDING', it just means the Locator did not respond to the status request within the given time period.
It should not be taken as the Locator failed to start.

status

Attempts to determine the state of the Locator. The Locator's status will be in only 1 of 2 possible states,
either ONLINE or OFFLINE. This method behaves differently depending on which parameters were specified when
the LocatorLauncher was constructed with an instance of Builder. If either the 'dir' or the 'pid' command-line
option were specified, then an attempt is made to determine the Locator's status by using the dir or pid to
correctly identify the Locator's MemberMXBean registered in the MBeanServer of the Locator's JVM, and invoking
the 'status' operation. The same behavior occurs if the caller specified the Locator's GemFire member name or ID.
However, if 'dir' or 'pid' were not specified, then determining the Locator's status defaults to using the
configured bind address and port. If the bind address or port was not specified when using the Builder to
construct a LocatorLauncher instance, then the defaults for both bind address and port are used. In either case,
an actual TCP/IP request is made to the Locator's ServerSocket to ensure it is listening for client requests.
This is true even when the LocatorLauncher is used in-process by calling the API.
If the conditions above hold, then the Locator is deemed to be 'ONLINE', otherwise, the Locator is considered
'OFFLINE'.

stop

Stop shuts the running Locator down. Using the API, the Locator is requested to stop by calling the Locator
object's 'stop' method. Internally, this method is no different than using the LocatorLauncher class from the
command-line or from within GemFire shell (Gfsh). In every single case, stop sends a TCP/IP 'shutdown' request
on the configured address/port to which the Locator is bound and listening.
If the "shutdown" request is successful, then the Locator will be 'STOPPED'. Otherwise, the Locator is considered
'OFFLINE' since the actual state cannot be fully assessed (as in the application process in which the Locator was
hosted may still be running and the Locator object may still exist even though it is no longer responding to
location-based requests). The later is particularly important in cases where the system resources (such as
Sockets) may not have been cleaned up yet. Therefore, by returning a status of 'OFFLINE', the value is meant to
reflect this in-deterministic state.

Returns:

a LocatorState indicating the state of the Locator after stop has been requested.