LocatorLauncher.Builder (Apache Geode 1.8.0)
Date: 2018-11-29

org.apache.geode.distributed

## Class LocatorLauncher.Builder

- java.lang.Object
- - org.apache.geode.distributed.LocatorLauncher.Builder

- Enclosing class:
    LocatorLauncher

      public static class LocatorLauncher.Builder
      extends java.lang.Object

  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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static LocatorLauncher.Command` | `DEFAULT_COMMAND`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Builder()` Default constructor used to create an instance of the Builder class for programmatical access.
    `Builder(java.lang.String... args)` Constructor used to create and configure an instance of the Builder class with the specified arguments, often passed from the command-line when launching an instance of this class from the command-line using the Java launcher.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `LocatorLauncher` | `build()` Validates the Builder configuration settings and then constructs an instance of the LocatorLauncher class to invoke operations on a GemFire Locator.
    `java.net.InetAddress` | `getBindAddress()` Gets the IP address to which the Locator has bound itself listening for client requests.
    `LocatorLauncher.Command` | `getCommand()` Gets the Locator launcher command used during the invocation of the LocatorLauncher.
    `java.lang.Boolean` | `getDebug()` Determines whether the new instance of the LocatorLauncher will be set to debug mode.
    `java.lang.Boolean` | `getDeletePidFileOnStop()` Determines whether the Geode Locator should delete the pid file when its service stops or when the JVM exits.
    `java.util.Properties` | `getDistributedSystemProperties()` Gets the GemFire Distributed System (cluster) Properties configuration.
    `java.lang.Boolean` | `getForce()` Gets the boolean value used by the Locator to determine if it should overwrite the PID file if it already exists.
    `java.lang.Boolean` | `getHelp()` Determines whether the new instance of LocatorLauncher will be used to output help information for either a specific command, or for using LocatorLauncher in general.
    `java.lang.String` | `getHostnameForClients()` Gets the hostname used by clients to lookup the Locator.
    `java.lang.String` | `getMemberName()` Gets the member name of this Locator in GemFire.
    `java.lang.Integer` | `getPid()` Gets the process ID (PID) of the running Locator indicated by the user as an argument to the LocatorLauncher.
    `java.lang.Integer` | `getPort()` Gets the port number used by the Locator to listen for client requests.
    `java.lang.Boolean` | `getRedirectOutput()` Determines whether the new instance of LocatorLauncher will redirect output to system logs when starting a Locator.
    `java.lang.String` | `getWorkingDirectory()` Gets the working directory pathname in which the Locator will be ran.
    `protected void` | `parseArguments(java.lang.String... args)` Parses an array of arguments to configure this Builder with the intent of constructing a Locator launcher to invoke a Locator.
    `protected void` | `parseCommand(java.lang.String... args)` Iterates the list of arguments in search of the target Locator launcher command.
    `protected void` | `parseMemberName(java.lang.String... args)` Iterates the list of arguments in search of the Locator's GemFire member name.
    `LocatorLauncher.Builder` | `set(java.lang.String propertyName, java.lang.String propertyValue)` Sets a GemFire Distributed System Property.
    `LocatorLauncher.Builder` | `setBindAddress(java.lang.String bindAddress)` Sets the IP address as an java.net.InetAddress to which the Locator has bound itself listening for client requests.
    `LocatorLauncher.Builder` | `setCommand(LocatorLauncher.Command command)` Sets the Locator launcher command used during the invocation of the LocatorLauncher
    `LocatorLauncher.Builder` | `setDebug(java.lang.Boolean debug)` Sets whether the new instance of the LocatorLauncher will be set to debug mode.
    `LocatorLauncher.Builder` | `setDeletePidFileOnStop(java.lang.Boolean deletePidFileOnStop)` Sets whether the Geode Locator should delete the pid file when its service stops or when the JVM exits.
    `LocatorLauncher.Builder` | `setForce(java.lang.Boolean force)` Sets the boolean value used by the Locator to determine if it should overwrite the PID file if it already exists.
    `LocatorLauncher.Builder` | `setHelp(java.lang.Boolean help)` Sets whether the new instance of LocatorLauncher will be used to output help information for either a specific command, or for using LocatorLauncher in general.
    `LocatorLauncher.Builder` | `setHostnameForClients(java.lang.String hostnameForClients)` Sets the hostname used by clients to lookup the Locator.
    `LocatorLauncher.Builder` | `setMemberName(java.lang.String memberName)` Sets the member name of the Locator in GemFire.
    `LocatorLauncher.Builder` | `setPid(java.lang.Integer pid)` Sets the process ID (PID) of the running Locator indicated by the user as an argument to the LocatorLauncher.
    `LocatorLauncher.Builder` | `setPort(java.lang.Integer port)` Sets the port number used by the Locator to listen for client requests.
    `LocatorLauncher.Builder` | `setRedirectOutput(java.lang.Boolean redirectOutput)` Sets whether the new instance of LocatorLauncher will redirect output to system logs when starting a Locator.
    `LocatorLauncher.Builder` | `setWorkingDirectory(java.lang.String workingDirectory)` Sets the working directory in which the Locator will be ran.
    `protected void` | `validate()` Validates the configuration settings and properties of this Builder, ensuring that all invariants have been met.
    `protected void` | `validateOnStart()` Validates the arguments passed to the Builder when the 'start' command has been issued.
    `protected void` | `validateOnStatus()` Validates the arguments passed to the Builder when the 'status' command has been issued.
    `protected void` | `validateOnStop()` Validates the arguments passed to the Builder when the 'stop' command has been issued.

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

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

- - ### Field Detail

    - #### DEFAULT_COMMAND

          protected static final LocatorLauncher.Command DEFAULT_COMMAND

  - ### Constructor Detail

    - #### Builder

          public Builder()

      Default constructor used to create an instance of the Builder class for programmatical access.

    - #### Builder

          public Builder(java.lang.String... args)

      Constructor used to create and configure an instance of the Builder class with the specified arguments, often passed from the command-line when launching an instance of this class from the command-line using the Java launcher.
      Parameters:
        `args` - the array of arguments used to configure the Builder.

  - ### Method Detail

    - #### parseArguments

          protected void parseArguments(java.lang.String... args)

      Parses an array of arguments to configure this Builder with the intent of constructing a Locator launcher to invoke a Locator. This method is called to parse the arguments specified by the user on the command-line.
      Parameters:
        `args` - the array of arguments used to configure this Builder and create an instance of LocatorLauncher.

    - #### parseCommand

          protected void parseCommand(java.lang.String... args)

      Iterates the list of arguments in search of the target Locator launcher command.
      Parameters:
        `args` - an array of arguments from which to search for the Locator launcher command.
      See Also:
        `LocatorLauncher.Command.valueOfName(String)`, `parseArguments(String...)`

    - #### parseMemberName

          protected void parseMemberName(java.lang.String... args)

      Iterates the list of arguments in search of the Locator's GemFire member name. If the argument does not start with '-' or is not the name of a Locator launcher command, then the value is presumed to be the member name for the Locator in GemFire.
      Parameters:
        `args` - the array of arguments from which to search for the Locator's member name in GemFire.
      See Also:
        `LocatorLauncher.Command.isCommand(String)`, `parseArguments(String...)`

    - #### getCommand

          public LocatorLauncher.Command getCommand()

      Gets the Locator launcher command used during the invocation of the LocatorLauncher.
      Returns:
        the Locator launcher command used to invoke (run) the LocatorLauncher class.
      See Also:
        `setCommand(org.apache.geode.distributed.LocatorLauncher.Command)`, `LocatorLauncher.Command`

    - #### setCommand

          public LocatorLauncher.Builder setCommand(LocatorLauncher.Command command)

      Sets the Locator launcher command used during the invocation of the LocatorLauncher
      Parameters:
        `command` - the targeted Locator launcher command used during the invocation (run) of LocatorLauncher.
      Returns:
        this Builder instance.
      See Also:
        `getCommand()`, `LocatorLauncher.Command`

    - #### getDebug

          public java.lang.Boolean getDebug()

      Determines whether the new instance of the LocatorLauncher will be set to debug mode.
      Returns:
        a boolean value indicating whether debug mode is enabled or disabled.
      See Also:
        `setDebug(Boolean)`

    - #### setDebug

          public LocatorLauncher.Builder setDebug(java.lang.Boolean debug)

      Sets whether the new instance of the LocatorLauncher will be set to debug mode.
      Parameters:
        `debug` - a boolean value indicating whether debug mode is to be enabled or disabled.
      Returns:
        this Builder instance.
      See Also:
        `getDebug()`

    - #### getDeletePidFileOnStop

          public java.lang.Boolean getDeletePidFileOnStop()

      Determines whether the Geode Locator should delete the pid file when its service stops or when the JVM exits.
      Returns:
        a boolean value indicating if the pid file should be deleted when this service stops or when the JVM exits.
      See Also:
        `setDeletePidFileOnStop(Boolean)`

    - #### setDeletePidFileOnStop

          public LocatorLauncher.Builder setDeletePidFileOnStop(java.lang.Boolean deletePidFileOnStop)

      Sets whether the Geode Locator should delete the pid file when its service stops or when the JVM exits.
      Parameters:
        `deletePidFileOnStop` - a boolean value indicating if the pid file should be deleted when this service stops or when the JVM exits.
      Returns:
        this Builder instance.
      See Also:
        `getDeletePidFileOnStop()`

    - #### getDistributedSystemProperties

          public java.util.Properties getDistributedSystemProperties()

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

    - #### getForce

          public java.lang.Boolean getForce()

      Gets the boolean value used by the Locator to determine if it should overwrite the PID file if it already exists.
      Returns:
        the boolean value specifying whether or not to overwrite the PID file if it already exists.
      See Also:
        `setForce(Boolean)`

    - #### setForce

          public LocatorLauncher.Builder setForce(java.lang.Boolean force)

      Sets the boolean value used by the Locator to determine if it should overwrite the PID file if it already exists.
      Parameters:
        `force` - a boolean value indicating whether to overwrite the PID file when it already exists.
      Returns:
        this Builder instance.
      See Also:
        `getForce()`

    - #### getHelp

          public java.lang.Boolean getHelp()

      Determines whether the new instance of LocatorLauncher will be used to output help information for either a specific command, or for using LocatorLauncher in general.
      Returns:
        a boolean value indicating whether help will be output during the invocation of LocatorLauncher.
      See Also:
        `setHelp(Boolean)`

    - #### setHelp

          public LocatorLauncher.Builder setHelp(java.lang.Boolean help)

      Sets whether the new instance of LocatorLauncher will be used to output help information for either a specific command, or for using LocatorLauncher in general.
      Parameters:
        `help` - a boolean indicating whether help information is to be displayed during invocation of LocatorLauncher.
      Returns:
        this Builder instance.
      See Also:
        `getHelp()`

    - #### getBindAddress

          public java.net.InetAddress getBindAddress()

      Gets the IP address to which the Locator has bound itself listening for client requests.
      Returns:
        an InetAddress with the IP address or hostname on which the Locator is bound and listening.
      See Also:
        `setBindAddress(String)`, `InetAddress`

    - #### setBindAddress

          public LocatorLauncher.Builder setBindAddress(java.lang.String bindAddress)

      Sets the IP address as an java.net.InetAddress to which the Locator has bound itself listening for client requests.
      Parameters:
        `bindAddress` - the InetAddress with the IP address or hostname on which the Locator is bound and listening.
      Returns:
        this Builder instance.
      Throws:
        `java.lang.IllegalArgumentException` - wrapping the UnknownHostException if the IP address or hostname for the bind address is unknown.
      See Also:
        `getBindAddress()`, `InetAddress`

    - #### getHostnameForClients

          public java.lang.String getHostnameForClients()

      Gets the hostname used by clients to lookup the Locator.
      Returns:
        a String indicating the hostname Locator binding used in client lookups.
      See Also:
        `setHostnameForClients(String)`

    - #### setHostnameForClients

          public LocatorLauncher.Builder setHostnameForClients(java.lang.String hostnameForClients)

      Sets the hostname used by clients to lookup the Locator.
      Parameters:
        `hostnameForClients` - a String indicating the hostname Locator binding used in client lookups.
      Returns:
        this Builder instance.
      Throws:
        `java.lang.IllegalArgumentException` - if the hostname was not specified (is blank or empty), such as when the --hostname-for-clients command-line option may have been specified without any argument.
      See Also:
        `getHostnameForClients()`

    - #### getMemberName

          public java.lang.String getMemberName()

      Gets the member name of this Locator in GemFire.
      Returns:
        a String indicating the member name of this Locator in GemFire.
      See Also:
        `setMemberName(String)`

    - #### setMemberName

          public LocatorLauncher.Builder setMemberName(java.lang.String memberName)

      Sets the member name of the Locator in GemFire.
      Parameters:
        `memberName` - a String indicating the member name of this Locator in GemFire.
      Returns:
        this Builder instance.
      Throws:
        `java.lang.IllegalArgumentException` - if the member name is invalid.
      See Also:
        `getMemberName()`

    - #### getPid

          public java.lang.Integer getPid()

      Gets the process ID (PID) of the running Locator indicated by the user as an argument to the LocatorLauncher. This PID is used by the Locator launcher to determine the Locator's status, or invoke shutdown on the Locator.
      Returns:
        a user specified Integer value indicating the process ID of the running Locator.
      See Also:
        `setPid(Integer)`

    - #### setPid

          public LocatorLauncher.Builder setPid(java.lang.Integer pid)

      Sets the process ID (PID) of the running Locator indicated by the user as an argument to the LocatorLauncher. This PID will be used by the Locator launcher to determine the Locator's status, or invoke shutdown on the Locator.
      Parameters:
        `pid` - a user specified Integer value indicating the process ID of the running Locator.
      Returns:
        this Builder instance.
      Throws:
        `java.lang.IllegalArgumentException` - if the process ID (PID) is not valid (greater than zero if not null).
      See Also:
        `getPid()`

    - #### getPort

          public java.lang.Integer getPort()

      Gets the port number used by the Locator to listen for client requests. If the port was not specified, then the default Locator port (10334) is returned.
      Returns:
        the specified Locator port or the default port if unspecified.
      See Also:
        `setPort(Integer)`

    - #### setPort

          public LocatorLauncher.Builder setPort(java.lang.Integer port)

      Sets the port number used by the Locator to listen for client requests. The port number must be between 1 and 65535 inclusive.
      Parameters:
        `port` - an Integer value indicating the port used by the Locator to listen for client requests.
      Returns:
        this Builder instance.
      Throws:
        `java.lang.IllegalArgumentException` - if the port number is not valid.
      See Also:
        `getPort()`

    - #### getRedirectOutput

          public java.lang.Boolean getRedirectOutput()

      Determines whether the new instance of LocatorLauncher will redirect output to system logs when starting a Locator.
      Returns:
        a boolean value indicating if output will be redirected to system logs when starting a Locator
      See Also:
        `setRedirectOutput(Boolean)`

    - #### setRedirectOutput

          public LocatorLauncher.Builder setRedirectOutput(java.lang.Boolean redirectOutput)

      Sets whether the new instance of LocatorLauncher will redirect output to system logs when starting a Locator.
      Parameters:
        `redirectOutput` - a boolean value indicating if output will be redirected to system logs when starting a Locator.
      Returns:
        this Builder instance.
      See Also:
        `getRedirectOutput()`

    - #### getWorkingDirectory

          public java.lang.String getWorkingDirectory()

      Gets the working directory pathname in which the Locator will be ran. If the directory is unspecified, then working directory defaults to the current directory.
      Returns:
        a String indicating the working directory pathname.
      See Also:
        `setWorkingDirectory(String)`

    - #### setWorkingDirectory

          public LocatorLauncher.Builder setWorkingDirectory(java.lang.String workingDirectory)

      Sets the working directory in which the Locator will be ran. This also the directory in which all Locator files (such as log and license files) will be written. If the directory is unspecified, then the working directory defaults to the current directory.
      Parameters:
        `workingDirectory` - a String indicating the pathname of the directory in which the Locator will be ran.
      Returns:
        this Builder instance.
      Throws:
        `java.lang.IllegalArgumentException` - wrapping a FileNotFoundException if the working directory pathname cannot be found.
      See Also:
        `getWorkingDirectory()`, `FileNotFoundException`

    - #### set

          public LocatorLauncher.Builder set(java.lang.String propertyName,
                                             java.lang.String propertyValue)

      Sets a GemFire Distributed System Property.
      Parameters:
        `propertyName` - a String indicating the name of the GemFire Distributed System property as described in `ConfigurationProperties`
        `propertyValue` - a String value for the GemFire Distributed System property.
      Returns:
        this Builder instance.

    - #### validate

          protected void validate()

      Validates the configuration settings and properties of this Builder, ensuring that all invariants have been met. Currently, the only invariant constraining the Builder is that the user must specify the member name for the Locator in the GemFire distributed system as a command-line argument, or by setting the memberName property programmatically using the corresponding setter method. If the member name is not given, then the user must have specified the pathname to the gemfire.properties file before validate is called. It is then assumed, but not further validated, that the user has specified the Locator's member name in the properties file.
      Throws:
        `java.lang.IllegalStateException` - if the Builder is not properly configured.

    - #### validateOnStart

          protected void validateOnStart()

      Validates the arguments passed to the Builder when the 'start' command has been issued.
      See Also:
        `LocatorLauncher.Command.START`

    - #### validateOnStatus

          protected void validateOnStatus()

      Validates the arguments passed to the Builder when the 'status' command has been issued.
      See Also:
        `LocatorLauncher.Command.STATUS`

    - #### validateOnStop

          protected void validateOnStop()

      Validates the arguments passed to the Builder when the 'stop' command has been issued.
      See Also:
        `LocatorLauncher.Command.STOP`

    - #### build

          public LocatorLauncher build()

      Validates the Builder configuration settings and then constructs an instance of the LocatorLauncher class to invoke operations on a GemFire Locator.
      Returns:
        a newly constructed instance of LocatorLauncher configured with this Builder.
      See Also:
        `validate()`, `LocatorLauncher`