Shell (Apache ZooKeeper - Server 3.7.0 API)
Date: 2021-03-17

org.apache.zookeeper

## Class Shell

- java.lang.Object
- - org.apache.zookeeper.Shell

- Direct Known Subclasses:
    Shell.ShellCommandExecutor

      public abstract class Shell
      extends Object

  A base class for running a Unix command. `Shell` can be used to run unix commands like `du` or `df`. It also offers facilities to gate commands by time-intervals.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Shell.ExitCodeException` This is an IOException with exit code added.
    `static class` | `Shell.ShellCommandExecutor` A simple shell command executor.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `SET_GROUP_COMMAND`
    `static String` | `SET_OWNER_COMMAND` a Unix command to set owner
    `static String` | `SET_PERMISSION_COMMAND` a Unix command to set permission
    `protected long` | `timeOutInterval` Time after which the executing script would be timedout
    `static String` | `ULIMIT_COMMAND` a Unix command to get ulimit of a process.
    `static String` | `USER_NAME_COMMAND` a Unix command to get the current user's name
    `static boolean` | `WINDOWS` Set to true on Windows platforms

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Shell()`
    `Shell(long interval)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `execCommand(Map<String,String> env, String... cmd)` Static method to execute a shell command.
    `static String` | `execCommand(Map<String,String> env, String[] cmd, long timeout)` Static method to execute a shell command.
    `static String` | `execCommand(String... cmd)` Static method to execute a shell command.
    `protected abstract String[]` | `getExecString()` return an array containing the command name and its parameters
    `int` | `getExitCode()` get the exit code
    `static String[]` | `getGET_PERMISSION_COMMAND()` Return a Unix command to get permission information.
    `static String[]` | `getGroupsCommand()` a Unix command to get the current user's groups list
    `static String[]` | `getGroupsForUserCommand(String user)` a Unix command to get a given user's groups list
    `Process` | `getProcess()` get the current sub-process executing the given command
    `static String[]` | `getUlimitMemoryCommand(int memoryLimit)` Get the Unix command for setting the maximum virtual memory available to a given child process.
    `boolean` | `isTimedOut()` To check if the passed script to shell command executor timed out or not.
    `protected abstract void` | `parseExecResult(BufferedReader lines)` Parse the execution result
    `protected void` | `run()` check to see if a command needs to be executed and execute if needed
    `protected void` | `setEnvironment(Map<String,String> env)` set the environment for the command
    `protected void` | `setWorkingDirectory(File dir)` set the working directory

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

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

- - ### Field Detail

    - #### USER_NAME_COMMAND

          public static final String USER_NAME_COMMAND

      a Unix command to get the current user's name
      See Also:
        Constant Field Values

    - #### SET_PERMISSION_COMMAND

          public static final String SET_PERMISSION_COMMAND

      a Unix command to set permission
      See Also:
        Constant Field Values

    - #### SET_OWNER_COMMAND

          public static final String SET_OWNER_COMMAND

      a Unix command to set owner
      See Also:
        Constant Field Values

    - #### SET_GROUP_COMMAND

          public static final String SET_GROUP_COMMAND

      See Also:
        Constant Field Values

    - #### timeOutInterval

          protected long timeOutInterval

      Time after which the executing script would be timedout

    - #### ULIMIT_COMMAND

          public static final String ULIMIT_COMMAND

      a Unix command to get ulimit of a process.
      See Also:
        Constant Field Values

    - #### WINDOWS

          public static final boolean WINDOWS

      Set to true on Windows platforms

  - ### Constructor Detail

    - #### Shell

          public Shell()

    - #### Shell

          public Shell(long interval)

      Parameters:
        `interval` - the minimum duration to wait before re-executing the command.

  - ### Method Detail

    - #### getGroupsCommand

          public static String[] getGroupsCommand()

      a Unix command to get the current user's groups list

    - #### getGroupsForUserCommand

          public static String[] getGroupsForUserCommand(String user)

      a Unix command to get a given user's groups list

    - #### getGET_PERMISSION_COMMAND

          public static String[] getGET_PERMISSION_COMMAND()

      Return a Unix command to get permission information.

    - #### getUlimitMemoryCommand

          public static String[] getUlimitMemoryCommand(int memoryLimit)

      Get the Unix command for setting the maximum virtual memory available to a given child process. This is only relevant when we are forking a process from within the Mapper or the Reducer implementations. Also see Hadoop Pipes and Hadoop Streaming. It also checks to ensure that we are running on a *nix platform else (e.g. in Cygwin/Windows) it returns `null`.
      Parameters:
        `memoryLimit` - virtual memory limit
      Returns:
        a `String[]` with the ulimit command arguments or `null` if we are running on a non *nix platform or if the limit is unspecified.

    - #### setEnvironment

          protected void setEnvironment(Map<String,String> env)

      set the environment for the command
      Parameters:
        `env` - Mapping of environment variables

    - #### setWorkingDirectory

          protected void setWorkingDirectory(File dir)

      set the working directory
      Parameters:
        `dir` - The directory where the command would be executed

    - #### run

          protected void run()
                      throws IOException

      check to see if a command needs to be executed and execute if needed
      Throws:
        `IOException`

    - #### getExecString

          protected abstract String[] getExecString()

      return an array containing the command name and its parameters

    - #### parseExecResult

          protected abstract void parseExecResult(BufferedReader lines)
                                           throws IOException

      Parse the execution result
      Throws:
        `IOException`

    - #### getProcess

          public Process getProcess()

      get the current sub-process executing the given command
      Returns:
        process executing the command

    - #### getExitCode

          public int getExitCode()

      get the exit code
      Returns:
        the exit code of the process

    - #### isTimedOut

          public boolean isTimedOut()

      To check if the passed script to shell command executor timed out or not.
      Returns:
        if the script timed out.

    - #### execCommand

          public static String execCommand(String... cmd)
                                    throws IOException

      Static method to execute a shell command. Covers most of the simple cases without requiring the user to implement the `Shell` interface.
      Parameters:
        `cmd` - shell command to execute.
      Returns:
        the output of the executed command.
      Throws:
        `IOException`

    - #### execCommand

          public static String execCommand(Map<String,String> env,
                                           String[] cmd,
                                           long timeout)
                                    throws IOException

      Static method to execute a shell command. Covers most of the simple cases without requiring the user to implement the `Shell` interface.
      Parameters:
        `env` - the map of environment key=value
        `cmd` - shell command to execute.
        `timeout` - time in milliseconds after which script should be marked timeout
      Returns:
        the output of the executed command.o
      Throws:
        `IOException`

    - #### execCommand

          public static String execCommand(Map<String,String> env,
                                           String... cmd)
                                    throws IOException

      Static method to execute a shell command. Covers most of the simple cases without requiring the user to implement the `Shell` interface.
      Parameters:
        `env` - the map of environment key=value
        `cmd` - shell command to execute.
      Returns:
        the output of the executed command.
      Throws:
        `IOException`

Copyright © 2008–2021 The Apache Software Foundation. All rights reserved.