LocatorLauncher (Apache Geode 2.0.2)
Description: declaration: package: org.apache.geode.distributed, class: LocatorLauncher

Package org.apache.geode.distributed

# Class LocatorLauncher

java.lang.Object
org.apache.geode.distributed.AbstractLauncher<String>
org.apache.geode.distributed.LocatorLauncher

All Implemented Interfaces:
  `Runnable`

public class LocatorLauncher extends AbstractLauncher<String>
The LocatorLauncher class is a launcher for a Geode Locator.

Since:
  GemFire 7.0
See Also:
  - `AbstractLauncher`
  - `ServerLauncher`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `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.
  `static enum`
  `LocatorLauncher.Command`
  An enumerated type representing valid commands to the Locator launcher.
  `static class`
  `LocatorLauncher.LocatorState`
  The LocatorState is an immutable type representing the state of the specified Locator at any given moment in time.

  ## Nested classes/interfaces inherited from class org.apache.geode.distributed.AbstractLauncher

  `AbstractLauncher.ServiceState<T extends Comparable<T>>, AbstractLauncher.Status`

- ## Field Summary

  ### Fields inherited from class org.apache.geode.distributed.AbstractLauncher

  `DEFAULT_FORCE, DEFAULT_WORKING_DIRECTORY, logger, MEMBER_NAME_ERROR_MESSAGE, OPTION_PREFIX, READ_PID_FILE_TIMEOUT_MILLIS, running, SIGNAL_HANDLER_REGISTRATION_SYSTEM_PROPERTY, WORKING_DIRECTORY_NOT_FOUND_ERROR_MESSAGE, WORKING_DIRECTORY_OPTION_NOT_VALID_ERROR_MESSAGE`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `InetAddress`
  `getBindAddress()`
  Gets the IP address of the NIC to which the Locator has bound itself listening for client requests.
  `protected String`
  `getBindAddressAsString()`
  Gets the host, as either hostname or IP address, on which the Locator was bound and running.
  `String`
  `getBindAddressString()`
  `Cache`
  `getCache()`
  Gets a reference to the `Cache` that was created by this `LocatorLauncher`.
  `LocatorLauncher.Command`
  `getCommand()`
  Get the Locator launcher command used to invoke the Locator.
  `protected Properties`
  `getDistributedSystemProperties()`
  Creates a Properties object with configuration settings that the launcher has that should take precedence over anything the user has defined in their gemfire properties file.
  `String`
  `getHostnameForClients()`
  Gets the hostname that clients will use to lookup the running Locator.
  `String`
  `getId()`
  Gets an identifier that uniquely identifies and represents the Locator associated with this launcher.
  `static LocatorLauncher`
  `getInstance()`
  Gets the instance of the LocatorLauncher used to launch the Geode Locator, or null if this VM does not have an instance of LocatorLauncher indicating no Geode Locator is running.
  `Locator`
  `getLocator()`
  Gets a reference to the `Locator` that was created by this `LocatorLauncher`.
  `protected File`
  `getLocatorPidFile()`
  Gets a File reference with the path to the PID file for the Locator.
  `static LocatorLauncher.LocatorState`
  `getLocatorState()`
  Gets the LocatorState for this process or null if this process was not launched using this VM's LocatorLauncher reference.
  `String`
  `getLogFileName()`
  Gets the name of the log file used to log information about this Locator.
  `String`
  `getMemberName()`
  Gets the name of this member (this Locator) in the Geode distributed system and determined by the 'name' Geode property.
  `Integer`
  `getPid()`
  Gets the user-specified process ID (PID) of the running Locator that LocatorLauncher uses to issue status and stop commands to the Locator.
  `Integer`
  `getPort()`
  Gets the port number on which the Locator listens for client requests.
  `String`
  `getPortAsString()`
  Gets the port number represented as a String value.
  `Properties`
  `getProperties()`
  Gets the Geode Distributed System (cluster) Properties.
  `String`
  `getServiceName()`
  Gets the name for a Geode Locator.
  `String`
  `getWorkingDirectory()`
  Gets the working directory pathname in which the Locator will be run.
  `void`
  `help(LocatorLauncher.Command command)`
  Displays help for the specified Locator launcher command to standard output.
  `boolean`
  `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.
  `boolean`
  `isHelping()`
  Determines whether this launcher will be used to display help information.
  `boolean`
  `isRedirectingOutput()`
  Determines whether this launcher will redirect output to system logs when starting a new Locator process.
  `protected boolean`
  `isStoppable()`
  Determines whether the Locator can be stopped in-process, such as when a Locator is embedded in an application and the LocatorLauncher API is being used.
  `static void`
  `main(String... args)`
  Launches a Geode Locator from the command-line configured with the given arguments.
  `void`
  `run()`
  The Runnable method used to launch the Locator with the specified command.
  `LocatorLauncher.LocatorState`
  `start()`
  Starts a Locator running on the specified port and bind address, as determined by getPort and getSocketAddress respectively, defaulting to 10334 and 'localhost' if not specified, with both peer and server location enabled.
  `LocatorLauncher.LocatorState`
  `status()`
  Attempts to determine the state of the Locator.
  `org.apache.geode.cache.client.internal.locator.LocatorStatusResponse`
  `statusForLocator(int port, String hostname)`
  Returns the status of the locator on the given host and port
  `org.apache.geode.cache.client.internal.locator.LocatorStatusResponse`
  `statusForLocator(int port, InetAddress bindAddressArg)`
  Returns the status of the locator on the given host and port.
  `static org.apache.geode.cache.client.internal.locator.LocatorStatusResponse`
  `statusLocator(int port, InetAddress bindAddress)`
  Deprecated.
  in Geode 1.12.
  `LocatorLauncher.LocatorState`
  `stop()`
  Stop shuts the running Locator down.
  `void`
  `usage()`
  Displays usage information on the proper invocation of the LocatorLauncher from the command-line to standard output.
  `LocatorLauncher.LocatorState`
  `waitOnLocator()`
  Waits on the Locator to stop causing the calling Thread to join with the Locator's location-based services Thread.
  `LocatorLauncher.LocatorState`
  `waitOnStatusResponse(long timeout, long interval, TimeUnit timeUnit)`
  Waits for a Locator status request response to be returned up to the specified timeout in the given unit of time.

  ### Methods inherited from class org.apache.geode.distributed.AbstractLauncher

  `assertPortAvailable, assertPortAvailable, debug, debug, getDistributedSystemProperties, getLogFile, getLogFileCanonicalPath, getMember, getMemberId, info, isDebugging, isRunning, isSet, loadGemFireProperties, redirectOutput, setDebug, version`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### main

    public static void main(String... args)
    Launches a Geode Locator from the command-line configured with the given arguments.
    Parameters:
      `args` - the command-line arguments used to configure the Geode Locator at runtime.

  - ### getInstance

    public static LocatorLauncher getInstance()
    Gets the instance of the LocatorLauncher used to launch the Geode Locator, or null if this VM does not have an instance of LocatorLauncher indicating no Geode Locator is running.
    Returns:
      the instance of LocatorLauncher used to launcher a Geode Locator in this VM.

  - ### getLocatorState

    public static LocatorLauncher.LocatorState getLocatorState()
    Gets the LocatorState for this process or null if this process was not launched using this VM's LocatorLauncher reference.
    Returns:
      the LocatorState for this process or null.

  - ### statusLocator

    @Deprecated public static org.apache.geode.cache.client.internal.locator.LocatorStatusResponse statusLocator(int port, InetAddress bindAddress) throws IOException
    Deprecated.
    in Geode 1.12. Use statusForLocator() instance method instead. This static method does not use the properties set via the Builder.
    Returns the status of the locator on the given host and port
    Parameters:
      `port` - the port that the locator is listening on
      `bindAddress` - the IP address to which the locator's socket binds
    Returns:
      a `LocatorStatusResponse` representing the status of the locator
    Throws:
      `IOException` - if there is a problem interacting with the locator

  - ### statusForLocator

    public org.apache.geode.cache.client.internal.locator.LocatorStatusResponse statusForLocator(int port, InetAddress bindAddressArg) throws IOException
    Returns the status of the locator on the given host and port. If you have endpoint identification enabled the preferred method is statusForLocator(int, String), which lets you specify the locator's name that the locator has stored in its TLS certificate
    Parameters:
      `port` - the port that the locator is listening on
      `bindAddressArg` - the IP address to which the locator's socket binds
    Returns:
      a `LocatorStatusResponse` representing the status of the locator
    Throws:
      `IOException` - if there is a problem interacting with the locator

  - ### statusForLocator

    public org.apache.geode.cache.client.internal.locator.LocatorStatusResponse statusForLocator(int port, String hostname) throws IOException
    Returns the status of the locator on the given host and port
    Parameters:
      `port` - the port that the locator is listening on
      `hostname` - the host name or ip address that the locator is listening on.
    Returns:
      a `LocatorStatusResponse` representing the status of the locator
    Throws:
      `IOException` - if there is a problem interacting with the locator

  - ### getCache

    public Cache getCache()
    Gets a reference to the `Cache` that was created by this `LocatorLauncher`.
    Returns:
      a reference to the Cache
    See Also:
      - `Cache`

  - ### getLocator

    public Locator getLocator()
    Gets a reference to the `Locator` that was created by this `LocatorLauncher`.
    Returns:
      a reference to the Locator.
    See Also:
      - `Locator`

  - ### getId

    public String getId()
    Gets an identifier that uniquely identifies and represents the Locator associated with this launcher.
    Returns:
      a String value identifier to uniquely identify the Locator and it's launcher.
    See Also:
      - `getBindAddressAsString()`
      - `getPortAsString()`

  - ### getCommand

    public LocatorLauncher.Command getCommand()
    Get the Locator launcher command used to invoke the Locator.
    Returns:
      the Locator launcher command used to invoke the Locator.
    See Also:
      - `LocatorLauncher.Command`

  - ### isForcing

    public boolean 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.
    See Also:
      - `LocatorLauncher.Command`

  - ### isRedirectingOutput

    public boolean isRedirectingOutput()
    Determines whether this launcher will redirect output to system logs when starting a new Locator process.
    Returns:
      a boolean value indicating if this launcher will redirect output to system logs when starting a new Locator process

  - ### getBindAddress

    public InetAddress getBindAddress()
    Gets the IP address of the NIC to which the Locator has bound itself listening for client requests.
    Returns:
      an InetAddress object representing the configured bind address for the Locator.
    See Also:
      - `InetAddress`

  - ### getBindAddressAsString

    protected String getBindAddressAsString()
    Gets the host, as either hostname or IP address, on which the Locator was bound and running. An attempt is made to get the canonical hostname for IP address to which the Locator was bound for accepting client requests. If the bind address is null or localhost is unknown, then a default String value of "localhost/127.0.0.1" is returned. Note, this information is purely information and should not be used to re-construct state or for other purposes.
    Returns:
      the hostname or IP address of the host running the Locator, based on the bind-address, or 'localhost/127.0.0.1' if the bind address is null and localhost is unknown.
    See Also:
      - `InetAddress`
      - `getBindAddress()`

  - ### getHostnameForClients

    public String getHostnameForClients()
    Gets the hostname that clients will use to lookup the running Locator.
    Returns:
      a String indicating the hostname used by clients to lookup the Locator.

  - ### getLogFileName

    public String getLogFileName()
    Gets the name of the log file used to log information about this Locator.
    Specified by:
      `getLogFileName` in class `AbstractLauncher<String>`
    Returns:
      a String value indicating the name of this Locator's log file.

  - ### getMemberName

    public String getMemberName()
    Gets the name of this member (this Locator) in the Geode distributed system and determined by the 'name' Geode property.
    Overrides:
      `getMemberName` in class `AbstractLauncher<String>`
    Returns:
      a String indicating the name of the member (this Locator) in the Geode distributed system.

  - ### getPid

    public Integer getPid()
    Gets the user-specified process ID (PID) of the running Locator that LocatorLauncher uses to issue status and stop commands to the Locator.
    Specified by:
      `getPid` in class `AbstractLauncher<String>`
    Returns:
      an Integer value indicating the process ID (PID) of the running Locator.

  - ### getPort

    public Integer getPort()
    Gets the port number on which the Locator listens for client requests.
    Returns:
      an Integer value indicating the port number on which the Locator is listening for client requests.

  - ### getPortAsString

    public String getPortAsString()
    Gets the port number represented as a String value. If the port number is null, the the default Locator port (10334) is returned;
    Returns:
      the port number as a String value.
    See Also:
      - `getPort()`

  - ### getProperties

    public Properties getProperties()
    Gets the Geode Distributed System (cluster) Properties.
    Returns:
      a Properties object containing the configuration settings for the Geode Distributed System (cluster).
    See Also:
      - `Properties`

  - ### getServiceName

    public String getServiceName()
    Gets the name for a Geode Locator.
    Specified by:
      `getServiceName` in class `AbstractLauncher<String>`
    Returns:
      a String indicating the name for a Geode Locator.

  - ### getWorkingDirectory

    public String getWorkingDirectory()
    Gets the working directory pathname in which the Locator will be run.
    Overrides:
      `getWorkingDirectory` in class `AbstractLauncher<String>`
    Returns:
      a String value indicating the pathname of the Locator's working directory.

  - ### help

    public void help(LocatorLauncher.Command command)
    Displays help for the specified Locator launcher command to standard output. If the Locator launcher command is unspecified, then usage information is displayed instead.
    Parameters:
      `command` - the Locator launcher command in which to display help information.
    See Also:
      - `usage()`

  - ### usage

    public void usage()
    Displays usage information on the proper invocation of the LocatorLauncher from the command-line to standard output.
    See Also:
      - `help(org.apache.geode.distributed.LocatorLauncher.Command)`

  - ### 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().
    See Also:
      - `Runnable`
      - `LocatorLauncher.Command`
      - `start()`
      - `waitOnLocator()`
      - `status()`
      - `stop()`
      - `AbstractLauncher.version()`
      - `help(org.apache.geode.distributed.LocatorLauncher.Command)`
      - `usage()`

  - ### getLocatorPidFile

    protected File getLocatorPidFile()
    Gets a File reference with the path to the PID file for the Locator.
    Returns:
      a File reference to the path of the Locator's PID file.

  - ### start

    public LocatorLauncher.LocatorState start()
    Starts a Locator running on the specified port and bind address, as determined by getPort and getSocketAddress 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'.
    Returns:
      a LocatorState to reflect the state of the Locator after start.
    Throws:
      `RuntimeException` - if the Locator failed to start for any reason.
      `IllegalStateException` - if the Locator is already running.
    See Also:
      - `failOnStart(Throwable)`
      - `getBindAddress()`
      - `getDistributedSystemProperties()`
      - `isForcing()`
      - `AbstractLauncher.getLogFile()`
      - `getLocatorPidFile()`
      - `getPort()`
      - `status()`
      - `stop()`
      - `waitOnLocator()`
      - `waitOnStatusResponse(long, long, java.util.concurrent.TimeUnit)`
      - `LocatorLauncher.LocatorState`
      - `AbstractLauncher.Status.NOT_RESPONDING`
      - `AbstractLauncher.Status.ONLINE`
      - `AbstractLauncher.Status.STARTING`

  - ### getDistributedSystemProperties

    protected Properties getDistributedSystemProperties()
    Description copied from class: `AbstractLauncher`
    Creates a Properties object with configuration settings that the launcher has that should take precedence over anything the user has defined in their gemfire properties file.
    Overrides:
      `getDistributedSystemProperties` in class `AbstractLauncher<String>`
    Returns:
      a Properties object with GemFire properties that the launcher has defined.
    See Also:
      - `AbstractLauncher.getDistributedSystemProperties(java.util.Properties)`
      - `Properties`

  - ### waitOnLocator

    public LocatorLauncher.LocatorState waitOnLocator()
    Waits on the Locator to stop causing the calling Thread to join with the Locator's location-based services Thread.
    Returns:
      the Locator's status once it stops.
    Throws:
      `AssertionError` - if the Locator has not been started and the reference is null (assertions must be enabled for the error to be thrown).
    See Also:
      - `failOnStart(Throwable)`
      - `AbstractLauncher.Status`
      - `LocatorLauncher.LocatorState`

  - ### waitOnStatusResponse

    public LocatorLauncher.LocatorState waitOnStatusResponse(long timeout, long interval, TimeUnit timeUnit)
    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.
    See Also:
      - `waitOnLocator()`

  - ### status

    public LocatorLauncher.LocatorState 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 Geode 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'.
    Returns:
      the Locator's state.
    See Also:
      - `start()`
      - `stop()`
      - `AbstractLauncher.Status`
      - `LocatorLauncher.LocatorState`

  - ### isStoppable

    protected boolean isStoppable()
    Determines whether the Locator can be stopped in-process, such as when a Locator is embedded in an application and the LocatorLauncher API is being used.
    Returns:
      a boolean indicating whether the Locator can be stopped in-process (the application's process with an embedded Locator).

  - ### stop

    public LocatorLauncher.LocatorState 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 Geode 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.
    See Also:
      - `start()`
      - `status()`
      - `LocatorLauncher.LocatorState`
      - `AbstractLauncher.Status.NOT_RESPONDING`
      - `AbstractLauncher.Status.STOPPED`

  - ### getBindAddressString

    public String getBindAddressString()