org.rhq.enterprise.communications.util.prefs
Class Setup

java.lang.Object
  org.rhq.enterprise.communications.util.prefs.Setup

public class Setup
extends Object

This provides a way to initially setup a set of preferences. Normally, this is used when a new installation is laid down and the user needs to be asked for some preference values to customize the installation with the user's own settings. This could concievably also be used to customize any set of preferences, even those that already exist or those that have recently been upgraded.

Author:

John Mazzitelli

Constructor Summary

Setup(Preferences preferences, String intro_message, List<SetupInstruction> instructions, PromptInput in, PrintWriter out)
Creates a new Setup object.

Method Summary

PromptInput	getIn() Returns the input object where the answers to the setup prompts will be read from.
List<SetupInstruction>	getInstructions() Returns the set of instructions that are used to ask the setup questions.
String	getIntroMessage() Returns the intro message that will be printed to the output stream before the setup() begins processing the instructions.
PrintWriter	getOut() Returns the output stream where the prompts and any other output messages will be written to.
Preferences	getPreferences() Returns the preferences that are to be customized via this setup instance.
protected String	preferencesDump(Preferences prefs) Given a set of preferences, this will dump each name/value in the returned string separated with a newline.
protected String	prompt(String prompt_message, String pref_name, String help_message, String default_value, PromptInput in, PrintWriter out, boolean no_echo) Prints the prompt message to the output stream and waits for the new value to be input.
boolean	setup() Performs the setup by asking questions and setting preferences according to this object's setup instructions.

Methods inherited from class java.lang.Object

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

Constructor Detail

Setup

public Setup(Preferences preferences,
             String intro_message,
             List<SetupInstruction> instructions,
             PromptInput in,
             PrintWriter out)

Creates a new Setup object.

Parameters:

preferences - the set of preferences that need to be customized

intro_message - a human-readable string that will be output prior to starting the setup() - this can be used to explain to the user what these set of preferences are for (may be null)

instructions - the set of instructions this class will use to customize the preferences

in - the input where the answers to the setup prompts will come from

out - the output stream where the setup prompts will be output

Method Detail

getPreferences

public Preferences getPreferences()

Returns the preferences that are to be customized via this setup instance.

Returns:

preferences

getIntroMessage

public String getIntroMessage()

Returns the intro message that will be printed to the output stream before the setup() begins processing the instructions. If this is null, it will be ignored.

Returns:

human-readable introductory message (may be null)

getInstructions

public List<SetupInstruction> getInstructions()

Returns the set of instructions that are used to ask the setup questions.

Returns:

instructions

getIn

public PromptInput getIn()

Returns the input object where the answers to the setup prompts will be read from.

Returns:

in

getOut

public PrintWriter getOut()

Returns the output stream where the prompts and any other output messages will be written to.

Returns:

out

setup

public boolean setup()

Performs the setup by asking questions and setting preferences according to this object's setup instructions.

Returns:

true if the setup finished; false if the user canceled the setup and reverted back to the original values

Throws:

RuntimeException - if failed to access the preferences backend store

prompt

protected String prompt(String prompt_message,
                        String pref_name,
                        String help_message,
                        String default_value,
                        PromptInput in,
                        PrintWriter out,
                        boolean no_echo)

Prints the prompt message to the output stream and waits for the new value to be input. If the input is empty (e.g. the user just hit the return key), an empty string is returned. A help message will be shown if the user asks for it.

Note that the default_value is only used to show in the prompt. Specifically, it will not be returned if the user simply hit the ENTER key without entering a value. In that case, an empty string is returned; the caller should detect this and set the value to the default as appropriate.

The returned value will be null if the user wants to rely on the system internal default and not set the preference value at all.

Parameters:

prompt_message - the prompt message printed to the output stream that tells the user what is being asked for

pref_name - the actual preference name that is to be set to the answer of the prompt

help_message - a more detailed help message that tells the user what is being asked for

default_value - what the value should be if the user just hits the ENTER key

in - where the user input is coming from

out - the stream where the prompt messages will be written

no_echo - if true, user should not see what is being typed at the prompt

Returns:

the new value entered by the user that came across in the input stream (may be null)

Throws:

RuntimeException - if failed to read from the input stream

preferencesDump

protected String preferencesDump(Preferences prefs)

Given a set of preferences, this will dump each name/value in the returned string separated with a newline.

Parameters:

prefs - the preferences whose values are to be dumped in the given string

Returns:

the preference name/value pairs separated by newlines