org.opends.server.util.cli
Class ConsoleApplication

java.lang.Object
  extended by org.opends.server.util.cli.ConsoleApplication
Direct Known Subclasses:
DSConfig, ErrorStreamConsoleApplication, InstallDS, JavaPropertiesTool, ManageTasks, OutputStreamConsoleApplication

public abstract class ConsoleApplication
extends java.lang.Object

This class provides an abstract base class which can be used as the basis of a console-based application.


Field Summary
protected static int CONFIRMATION_MAX_TRIES
          The maximum number of times we try to confirm.
 
Constructor Summary
protected ConsoleApplication(java.io.BufferedReader in, java.io.PrintStream out, java.io.PrintStream err)
          Creates a new console application instance.
protected ConsoleApplication(java.io.InputStream in, java.io.OutputStream out, java.io.OutputStream err)
          Creates a new console application instance.
 
Method Summary
protected  boolean askConfirmation(Message prompt, boolean defaultValue, java.util.logging.Logger logger)
          Commodity method that interactively confirms whether a user wishes to perform an action.
 boolean confirmAction(Message prompt, boolean defaultValue)
          Interactively confirms whether a user wishes to perform an action.
protected  javax.naming.ldap.InitialLdapContext createAdministrativeContext(java.lang.String host, int port, boolean useSSL, boolean useStartTLS, java.lang.String bindDn, java.lang.String pwd, ApplicationTrustManager trustManager)
          Returns an InitialLdapContext using the provided parameters.
protected  javax.naming.ldap.InitialLdapContext createInitialLdapContextInteracting(LDAPConnectionConsoleInteraction ci)
          Creates an Initial LDAP Context interacting with the user if the application is interactive.
 java.io.PrintStream getErrorStream()
          Gets the application error stream.
 java.io.BufferedReader getInputStream()
          Gets the application input stream.
 java.io.PrintStream getOutputStream()
          Gets the application output stream.
abstract  boolean isAdvancedMode()
          Indicates whether or not the user has requested advanced mode.
abstract  boolean isInteractive()
          Indicates whether or not the user has requested interactive behavior.
abstract  boolean isMenuDrivenMode()
          Indicates whether or not this console application is running in its menu-driven mode.
abstract  boolean isQuiet()
          Indicates whether or not the user has requested quiet output.
abstract  boolean isScriptFriendly()
          Indicates whether or not the user has requested script-friendly output.
abstract  boolean isVerbose()
          Indicates whether or not the user has requested verbose output.
 void pressReturnToContinue()
          Interactively prompts the user to press return to continue.
 void print(Message msg)
          Displays a message to the error stream.
 void println()
          Displays a blank line to the error stream.
 void println(Message msg)
          Displays a message to the error stream.
 void println(Message msg, int indent)
          Displays a message to the error stream indented by the specified number of columns.
 void printlnProgress()
          Displays a blank line to the output stream if we are not in quiet mode.
 void printProgress(Message msg)
          Displays a message to the output stream if we are not in quiet mode.
 void printVerboseMessage(Message msg)
          Displays a message to the error stream if verbose mode is enabled.
 java.lang.String readInput(Message prompt, java.lang.String defaultValue)
          Commodity method that interactively prompts (on error output) the user to provide a string value.
 java.lang.String readInput(Message prompt, java.lang.String defaultValue, java.util.logging.Logger logger)
          Commodity method that interactively prompts (on error output) the user to provide a string value.
 java.lang.String readLineOfInput(Message prompt)
          Interactively retrieves a line of input from the console.
 java.lang.String readPassword(Message prompt)
          Interactively retrieves a password from the console.
protected  java.lang.String readPassword(Message prompt, java.util.logging.Logger logger)
          Commodity method that interactively retrieves a password from the console.
 int readPort(Message prompt, int defaultValue)
          Interactively retrieves a port value from the console.
<T> T
readValidatedInput(Message prompt, ValidationCallback<T> validator)
          Interactively prompts for user input and continues until valid input is provided.
<T> T
readValidatedInput(Message prompt, ValidationCallback<T> validator, int maxTries)
          Interactively prompts for user input and continues until valid input is provided.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONFIRMATION_MAX_TRIES

protected static final int CONFIRMATION_MAX_TRIES
The maximum number of times we try to confirm.

See Also:
Constant Field Values
Constructor Detail

ConsoleApplication

protected ConsoleApplication(java.io.BufferedReader in,
                             java.io.PrintStream out,
                             java.io.PrintStream err)
Creates a new console application instance.

Parameters:
in - The application input stream.
out - The application output stream.
err - The application error stream.

ConsoleApplication

protected ConsoleApplication(java.io.InputStream in,
                             java.io.OutputStream out,
                             java.io.OutputStream err)
Creates a new console application instance.

Parameters:
in - The application input stream.
out - The application output stream.
err - The application error stream.
Method Detail

confirmAction

public final boolean confirmAction(Message prompt,
                                   boolean defaultValue)
                            throws CLIException
Interactively confirms whether a user wishes to perform an action. If the application is non-interactive, then the provided default is returned automatically.

Parameters:
prompt - The prompt describing the action.
defaultValue - The default value for the confirmation message. This will be returned if the application is non-interactive or if the user just presses return.
Returns:
Returns true if the user wishes the action to be performed, or false if they refused, or if an exception occurred.
Throws:
CLIException - If the user's response could not be read from the console for some reason.

getErrorStream

public final java.io.PrintStream getErrorStream()
Gets the application error stream.

Returns:
Returns the application error stream.

getInputStream

public final java.io.BufferedReader getInputStream()
Gets the application input stream.

Returns:
Returns the application input stream.

getOutputStream

public final java.io.PrintStream getOutputStream()
Gets the application output stream.

Returns:
Returns the application output stream.

isAdvancedMode

public abstract boolean isAdvancedMode()
Indicates whether or not the user has requested advanced mode.

Returns:
Returns true if the user has requested advanced mode.

isInteractive

public abstract boolean isInteractive()
Indicates whether or not the user has requested interactive behavior.

Returns:
Returns true if the user has requested interactive behavior.

isMenuDrivenMode

public abstract boolean isMenuDrivenMode()
Indicates whether or not this console application is running in its menu-driven mode. This can be used to dictate whether output should go to the error stream or not. In addition, it may also dictate whether or not sub-menus should display a cancel option as well as a quit option.

Returns:
Returns true if this console application is running in its menu-driven mode.

isQuiet

public abstract boolean isQuiet()
Indicates whether or not the user has requested quiet output.

Returns:
Returns true if the user has requested quiet output.

isScriptFriendly

public abstract boolean isScriptFriendly()
Indicates whether or not the user has requested script-friendly output.

Returns:
Returns true if the user has requested script-friendly output.

isVerbose

public abstract boolean isVerbose()
Indicates whether or not the user has requested verbose output.

Returns:
Returns true if the user has requested verbose output.

pressReturnToContinue

public final void pressReturnToContinue()
Interactively prompts the user to press return to continue. This method should be called in situations where a user needs to be given a chance to read some documentation before continuing (continuing may cause the documentation to be scrolled out of view).


println

public final void println()
Displays a blank line to the error stream.


println

public final void println(Message msg)
Displays a message to the error stream.

Parameters:
msg - The message.

print

public final void print(Message msg)
Displays a message to the error stream.

Parameters:
msg - The message.

printlnProgress

public final void printlnProgress()
Displays a blank line to the output stream if we are not in quiet mode.


printProgress

public final void printProgress(Message msg)
Displays a message to the output stream if we are not in quiet mode.

Parameters:
msg - The message.

println

public final void println(Message msg,
                          int indent)
Displays a message to the error stream indented by the specified number of columns.

Parameters:
msg - The message.
indent - The number of columns to indent.

printVerboseMessage

public final void printVerboseMessage(Message msg)
Displays a message to the error stream if verbose mode is enabled.

Parameters:
msg - The verbose message.

readLineOfInput

public final java.lang.String readLineOfInput(Message prompt)
                                       throws CLIException
Interactively retrieves a line of input from the console.

Parameters:
prompt - The prompt.
Returns:
Returns the line of input, or null if the end of input has been reached.
Throws:
CLIException - If the line of input could not be retrieved for some reason.

readInput

public java.lang.String readInput(Message prompt,
                                  java.lang.String defaultValue)
                           throws CLIException
Commodity method that interactively prompts (on error output) the user to provide a string value. Any non-empty string will be allowed (the empty string will indicate that the default should be used, if there is one).

Parameters:
prompt - The prompt to present to the user.
defaultValue - The default value to assume if the user presses ENTER without typing anything, or null if there should not be a default and the user must explicitly provide a value.
Returns:
The string value read from the user.
Throws:
CLIException - If the line of input could not be retrieved for some reason.

readInput

public java.lang.String readInput(Message prompt,
                                  java.lang.String defaultValue,
                                  java.util.logging.Logger logger)
Commodity method that interactively prompts (on error output) the user to provide a string value. Any non-empty string will be allowed (the empty string will indicate that the default should be used, if there is one). If an error occurs a message will be logged to the provided logger.

Parameters:
prompt - The prompt to present to the user.
defaultValue - The default value to assume if the user presses ENTER without typing anything, or null if there should not be a default and the user must explicitly provide a value.
logger - the Logger to be used to log the error message.
Returns:
The string value read from the user.

readPassword

public final java.lang.String readPassword(Message prompt)
                                    throws CLIException
Interactively retrieves a password from the console.

Parameters:
prompt - The password prompt.
Returns:
Returns the password.
Throws:
CLIException - If the password could not be retrieved for some reason.

readPassword

protected final java.lang.String readPassword(Message prompt,
                                              java.util.logging.Logger logger)
Commodity method that interactively retrieves a password from the console. If there is an error an error message is logged to the provided Logger and null is returned.

Parameters:
prompt - The password prompt.
logger - the Logger to be used to log the error message.
Returns:
Returns the password.

readPort

public final int readPort(Message prompt,
                          int defaultValue)
                   throws CLIException
Interactively retrieves a port value from the console.

Parameters:
prompt - The port prompt.
defaultValue - The port default value.
Returns:
Returns the port.
Throws:
CLIException - If the port could not be retrieved for some reason.

readValidatedInput

public final <T> T readValidatedInput(Message prompt,
                                      ValidationCallback<T> validator)
                           throws CLIException
Interactively prompts for user input and continues until valid input is provided.

Type Parameters:
T - The type of decoded user input.
Parameters:
prompt - The interactive prompt which should be displayed on each input attempt.
validator - An input validator responsible for validating and decoding the user's response.
Returns:
Returns the decoded user's response.
Throws:
CLIException - If an unexpected error occurred which prevented validation.

readValidatedInput

public final <T> T readValidatedInput(Message prompt,
                                      ValidationCallback<T> validator,
                                      int maxTries)
                           throws CLIException
Interactively prompts for user input and continues until valid input is provided.

Type Parameters:
T - The type of decoded user input.
Parameters:
prompt - The interactive prompt which should be displayed on each input attempt.
validator - An input validator responsible for validating and decoding the user's response.
maxTries - The maximum number of tries that we can make.
Returns:
Returns the decoded user's response.
Throws:
CLIException - If an unexpected error occurred which prevented validation or if the maximum number of tries was reached.

askConfirmation

protected final boolean askConfirmation(Message prompt,
                                        boolean defaultValue,
                                        java.util.logging.Logger logger)
                                 throws CLIException
Commodity method that interactively confirms whether a user wishes to perform an action. If the application is non-interactive, then the provided default is returned automatically. If there is an error an error message is logged to the provided Logger and the defaul value is returned.

Parameters:
prompt - The prompt describing the action.
defaultValue - The default value for the confirmation message. This will be returned if the application is non-interactive or if the user just presses return.
logger - the Logger to be used to log the error message.
Returns:
Returns true if the user wishes the action to be performed, or false if they refused.
Throws:
CLIException - if the user did not provide valid answer after a certain number of tries (ConsoleApplication.CONFIRMATION_MAX_TRIES)

createAdministrativeContext

protected javax.naming.ldap.InitialLdapContext createAdministrativeContext(java.lang.String host,
                                                                           int port,
                                                                           boolean useSSL,
                                                                           boolean useStartTLS,
                                                                           java.lang.String bindDn,
                                                                           java.lang.String pwd,
                                                                           ApplicationTrustManager trustManager)
                                                                    throws javax.naming.NamingException
Returns an InitialLdapContext using the provided parameters. We try to guarantee that the connection is able to read the configuration.

Parameters:
host - the host name.
port - the port to connect.
useSSL - whether to use SSL or not.
useStartTLS - whether to use StartTLS or not.
bindDn - the bind dn to be used.
pwd - the password.
trustManager - the trust manager.
Returns:
an InitialLdapContext connected.
Throws:
javax.naming.NamingException - if there was an error establishing the connection.

createInitialLdapContextInteracting

protected javax.naming.ldap.InitialLdapContext createInitialLdapContextInteracting(LDAPConnectionConsoleInteraction ci)
                                                                            throws ClientException
Creates an Initial LDAP Context interacting with the user if the application is interactive.

Parameters:
ci - the LDAPConnectionConsoleInteraction object that is assumed to have been already run.
Returns:
the initial LDAP context or null if the user did not accept to trust the certificates.
Throws:
ClientException - if there was an error establishing the connection.