com.sun.interview
Class PropertiesQuestion

java.lang.Object
  extended by com.sun.interview.Question
      extended by com.sun.interview.CompositeQuestion
          extended by com.sun.interview.PropertiesQuestion

public abstract class PropertiesQuestion
extends CompositeQuestion

A question which consists of many key-value pairs. The values are altered by the user, the key is immutable. The output of this question is a Properties object. The key in the properties object is always the internal name, not the internationalized name. If internationalized key names are supplied, they are used only for presentation. The presentation info is store here instead of in a renderer class because multiple clients need to render this question.

Since:
4.0

Nested Class Summary
static class PropertiesQuestion.BooleanConstraints
          Constraints allowing a value to be either a boolean or Yes/No response.
static class PropertiesQuestion.FilenameConstraints
          Constrains the response to filenames or paths, and allows chooser widgets to be rendered for the user when appropriate.
static class PropertiesQuestion.FloatConstraints
          Constraints specifying a floating point type.
static class PropertiesQuestion.IntConstraints
           
static class PropertiesQuestion.StringConstraints
          Value restrictions for string type responses.
static class PropertiesQuestion.ValueConstraints
           
 
Field Summary
protected  java.util.Properties value
          The current (default or latest) response to this question.
 
Fields inherited from class com.sun.interview.Question
interview, key, tag
 
Constructor Summary
protected PropertiesQuestion(Interview interview, java.lang.String tag)
          Create a question with a nominated tag.
protected PropertiesQuestion(Interview interview, java.lang.String tag, java.util.Properties props)
          Create a question with a nominated tag.
protected PropertiesQuestion(Interview interview, java.lang.String tag, java.lang.String[] keys)
          Create a question with a nominated tag.
 
Method Summary
 void clear()
          Clear any response to this question, resetting the value back to its initial state.
 void createGroup(java.lang.String name)
          Create a new group.
 java.lang.String getConstraintKeyFromRow(java.lang.Object[] values)
          Calculates constraint key for table row.
 PropertiesQuestion.ValueConstraints getConstraints(java.lang.String key)
           
 java.util.Properties getDefaultValue()
          Get the default response for this question.
 java.lang.String[][] getGroup(java.lang.String group)
          Get the keys which are registered with the given group.
 java.lang.String getGroupDisplayName(java.lang.String group)
          Get the display (localized) name of the group.
 java.lang.String[] getGroups()
          Get the names of the groups being used by the current set of values.
 java.lang.String[][] getInvalidKeys()
          Get the keys which are currently invalid and blocking the question (getNext() returning null).
 java.lang.String getKeyHeaderName()
          Get the header string for the column in the table that contains the key names.
 java.util.Enumeration getKeys()
          Get the set of keys currently used this question.
 java.lang.String getStringValue()
          Get the response to this question as a string.
 java.lang.String[][] getUngrouped()
           
 java.util.Properties getValue()
          Get the current (default or latest) response to this question.
 java.lang.String getValueHeaderName()
          Get the header string for the column in the table that contains the value names.
 java.util.Properties getValueOnPath()
          Verify this question is on the current path, and if it is, return the current value.
 boolean isEntryVisible(java.lang.String key)
          Determine if the given property is visible to the user.
 boolean isReadOnlyValue(java.lang.String key)
          Determine if a value is read-only.
 boolean isValueAlwaysValid()
          Check if the question always has a valid response.
 boolean isValueValid()
          Check if the question currently has a valid response.
 java.lang.String isValueValid(java.lang.String key)
          Convenience method for finding out the status of a particular value.
protected  void load(java.util.Map data)
          Load the value for this question from a dictionary, using the tag as the key.
protected static java.util.Properties load(java.lang.String s)
           
protected  void save(java.util.Map data)
          Save the value for this question in a dictionary, using the tag as the key.
 void setConstraints(java.lang.String key, PropertiesQuestion.ValueConstraints c)
          Apply constraints to a value.
 void setDefaultValue(java.util.Properties props)
          Set the default response for this question, used by the clear method.
 void setGroup(java.lang.String group, java.lang.String key)
          Set the presentation group to which the key(s) should belong.
 void setGroup(java.lang.String group, java.lang.String[] keys)
           
protected  void setKeys(java.lang.String[] keys, boolean localize)
          Set the keys to be shown in the properties table.
protected  void setProperties(java.util.Properties props)
          The current value will be set to all false;
 void setValue(java.util.Properties props)
          Private because we need to maintain internal consistency, especially with the i18n info.
 void setValue(java.lang.String newValue)
          Set the current value.
 void setValue(java.lang.String key, java.lang.String v)
          Set a specific property within this question.
 void updateProperties(java.lang.String[][] props)
          Update the given properties.
 void updateProperty(java.lang.String key, java.lang.String val)
          Update the given property.
 
Methods inherited from class com.sun.interview.Question
addMarker, equals, export, getChecklistItems, getHelpID, getImage, getInterview, getKey, getNext, getResourceString, getResourceString, getSummary, getTag, getText, getTextArgs, hashCode, hasMarker, isEnabled, isHidden, reload, removeMarker, setImage, setImage, setSummary, setText
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

value

protected java.util.Properties value
The current (default or latest) response to this question.

Constructor Detail

PropertiesQuestion

protected PropertiesQuestion(Interview interview,
                             java.lang.String tag)
Create a question with a nominated tag. If this constructor is used, the choices must be supplied separately.

Parameters:
interview - The interview containing this question.
tag - A unique tag to identify this specific question.

PropertiesQuestion

protected PropertiesQuestion(Interview interview,
                             java.lang.String tag,
                             java.util.Properties props)
Create a question with a nominated tag. Not recommended since this is not internationalized.

Parameters:
interview - The interview containing this question.
tag - A unique tag to identify this specific question.
props - The literal keys and values. A shallow copy of this is used.
Throws:
java.lang.NullPointerException - if choices is null

PropertiesQuestion

protected PropertiesQuestion(Interview interview,
                             java.lang.String tag,
                             java.lang.String[] keys)
Create a question with a nominated tag. The keys must be registered in the resource bundle for this question for internationalization purposes. They will be looked up by this questions tag, plus each of the key values.

Parameters:
interview - The interview containing this question.
tag - A unique tag to identify this specific question.
keys - Internal name of the keys
Throws:
java.lang.NullPointerException - if choices is null
Method Detail

setProperties

protected void setProperties(java.util.Properties props)
The current value will be set to all false;

Parameters:
props - The set of names for the choices for this question.
Throws:
java.lang.NullPointerException - if choices is null
See Also:
getValue()

setKeys

protected void setKeys(java.lang.String[] keys,
                       boolean localize)
Set the keys to be shown in the properties table. Previous properties are removed, and the new values are all the empty string. The current value will be set to an empty string.

Parameters:
keys - The set of names of the choices for this question.
localize - if false, the choices will be used directly as the display choices; otherwise the choices will be used to construct keys to get localized values from the interview's resource bundle.
Throws:
java.lang.NullPointerException - if choices is null
See Also:
getKeys()

getKeys

public java.util.Enumeration getKeys()
Get the set of keys currently used this question. Includes all hidden and read-only values as well.

Returns:
The set of keys (internal non-i18n value)
See Also:
setKeys(java.lang.String[], boolean)

getDefaultValue

public java.util.Properties getDefaultValue()
Get the default response for this question.

Returns:
the default response for this question.
See Also:
setDefaultValue(java.util.Properties)

setDefaultValue

public void setDefaultValue(java.util.Properties props)
Set the default response for this question, used by the clear method.

Parameters:
props - the default response for this question.
See Also:
getDefaultValue()

getValue

public java.util.Properties getValue()
Get the current (default or latest) response to this question.

Returns:
The current value - a cloned copy.
Throws:
java.lang.IllegalStateException - if no choices have been set, defining the set of responses to this question
See Also:
setValue(java.lang.String)

getValueOnPath

public java.util.Properties getValueOnPath()
                                    throws Interview.NotOnPathFault
Verify this question is on the current path, and if it is, return the current value.

Returns:
the current value of this question
Throws:
Interview.NotOnPathFault - if this question is not on the current path
See Also:
getValue()

getStringValue

public java.lang.String getStringValue()
Description copied from class: Question
Get the response to this question as a string.

Specified by:
getStringValue in class Question
Returns:
a string representing the current response to this question, or null.
See Also:
Question.setValue(String)

setValue

public void setValue(java.lang.String newValue)
Set the current value.

Specified by:
setValue in class Question
Parameters:
newValue - Value represented as a single string. May not be null. May be an empty string.
See Also:
getValue()

setValue

public void setValue(java.lang.String key,
                     java.lang.String v)
              throws Interview.Fault
Set a specific property within this question. The property must exist before it can be set, else a Fault is thrown to prevent unauthorized additions of properties to the question value.

Specified by:
setValue in class CompositeQuestion
Parameters:
key - the key of the property to set, must not be null
v - the new value for the property, must not be null
Throws:
Interview.Fault - if the key does not already exist in the question's value.
java.lang.NullPointerException - if either parameter is null
Interview.Fault - if the specified key does not exist in the question
See Also:
Question.getStringValue()

isValueValid

public boolean isValueValid()
Description copied from class: Question
Check if the question currently has a valid response.

Specified by:
isValueValid in class Question
Returns:
true if the question currently has a valid response, and false otherwise.

isValueAlwaysValid

public boolean isValueAlwaysValid()
Description copied from class: Question
Check if the question always has a valid response. This may be true, for example, for a choice question with a default response.

Specified by:
isValueAlwaysValid in class Question
Returns:
true if the question always has a valid response, and false otherwise.

clear

public void clear()
Clear any response to this question, resetting the value back to its initial state.

Specified by:
clear in class Question

load

protected void load(java.util.Map data)
Load the value for this question from a dictionary, using the tag as the key.

Specified by:
load in class Question
Parameters:
data - The map from which to load the value for this question.

load

protected static java.util.Properties load(java.lang.String s)

save

protected void save(java.util.Map data)
Save the value for this question in a dictionary, using the tag as the key.

Specified by:
save in class Question
Parameters:
data - The map in which to save the value for this question.

isReadOnlyValue

public boolean isReadOnlyValue(java.lang.String key)
Determine if a value is read-only.


isEntryVisible

public boolean isEntryVisible(java.lang.String key)
Determine if the given property is visible to the user. If it is not, the value is not presented in the GUI for editing and is hidden in any reports which show the state of the interview. Nonetheless, it is still present and can be altered manually on the command line or by editing the configuration file. So it is truly invisible, yet real.

Returns:
True if the entry is visible (default), false otherwise.

getInvalidKeys

public java.lang.String[][] getInvalidKeys()
Get the keys which are currently invalid and blocking the question (getNext() returning null). It is recommended but not required that this method return null if the question is not blocked (getNext() != null). This default implementation of this method is to check any ValueConstraint objects for each key and return those results. If you override this method, it is highly recommended that you allow this to take place, then add in any additional checking to the results provided by this base implementation.

Returns:
Invalid key in index zero, localized explanation in index one. Null means there are no invalid keys.

isValueValid

public final java.lang.String isValueValid(java.lang.String key)
Convenience method for finding out the status of a particular value. This method is final because subclasses should implement getInvalidKeys().

Parameters:
key - The key to query. Must not be null.
Returns:
The explanation for the value being invalid. Null if the value is reported as valid.
See Also:
getInvalidKeys()

setValue

public void setValue(java.util.Properties props)
Private because we need to maintain internal consistency, especially with the i18n info.


updateProperties

public void updateProperties(java.lang.String[][] props)
Update the given properties. New properties cannot be added this way.

Parameters:
props - Properties to update, keys in first index, values in the second.
Throws:
java.lang.IllegalArgumentException - If a property in props does not exist.

updateProperty

public void updateProperty(java.lang.String key,
                           java.lang.String val)
Update the given property. New properties cannot be added this way.

Parameters:
key - Property to update.
val - Value for the property.
Throws:
java.lang.IllegalArgumentException - If the property does not exist.

createGroup

public void createGroup(java.lang.String name)
Create a new group.

Throws:
java.lang.IllegalStateException - If the group requested already exists.

setGroup

public void setGroup(java.lang.String group,
                     java.lang.String key)
Set the presentation group to which the key(s) should belong. If the key is in another group, it will be removed from that one. The

Parameters:
group - internal name for the group. Internationalized version must be available in the resource bundle as tag+group.
key - Which keys to add to the group.
Throws:
java.lang.IllegalArgumentException - If an attempt is made to add to a group which does not exist.
java.lang.IllegalStateException - If an attempt is made to group a key which is not present.
See Also:
createGroup(java.lang.String)

setGroup

public void setGroup(java.lang.String group,
                     java.lang.String[] keys)

getGroups

public java.lang.String[] getGroups()
Get the names of the groups being used by the current set of values. Groups which are empty are not listed; groups may become empty if client code attempts to put a key in more than one group.

Returns:
Group names, null if no grouping is in use.
See Also:
setGroup(String,String), setGroup(String,String[])

getGroup

public java.lang.String[][] getGroup(java.lang.String group)
Get the keys which are registered with the given group.

Parameters:
group - Group name to query. Null returns the groupless keys.
Returns:
Null if the group is empty or does not exist, else the keys and values in this array.
See Also:
getGroups(), setGroup(java.lang.String, java.lang.String)

getUngrouped

public java.lang.String[][] getUngrouped()
Returns:
The keys and values which are not allocated to any group. Null if there are no ungrouped values.
See Also:
getGroup(java.lang.String), setGroup(java.lang.String, java.lang.String)

getGroupDisplayName

public java.lang.String getGroupDisplayName(java.lang.String group)
Get the display (localized) name of the group. The resource necessary is the question tag, with the group name and ".group" appended. That is jck.qTable.basic.group and jck.qTable.advanced.group.

Parameters:
group - The internal group name, as is used in the rest of this API.
Returns:
The localized group name, the generated bundle key if that cannot be found.

getKeyHeaderName

public java.lang.String getKeyHeaderName()
Get the header string for the column in the table that contains the key names. A short name is recommended for onscreen space considerations.

Returns:
A string describing the key column in the table.

getValueHeaderName

public java.lang.String getValueHeaderName()
Get the header string for the column in the table that contains the value names. A short name is recommended for onscreen space considerations.

Returns:
A string describing the value column in the table.

setConstraints

public void setConstraints(java.lang.String key,
                           PropertiesQuestion.ValueConstraints c)
Apply constraints to a value.

Throws:
java.lang.IllegalArgumentException - If the key supplied does not exist in the current data.
See Also:
PropertiesQuestion.ValueConstraints, PropertiesQuestion.IntConstraints, PropertiesQuestion.FloatConstraints, PropertiesQuestion.BooleanConstraints

getConstraintKeyFromRow

public java.lang.String getConstraintKeyFromRow(java.lang.Object[] values)
Calculates constraint key for table row. By default constraint key is a value of first column

Parameters:
values - Array of table row data
Returns:
a key

getConstraints

public PropertiesQuestion.ValueConstraints getConstraints(java.lang.String key)
Parameters:
key - The key for the value to get constraints for.
Returns:
Constraints object for the specified key, null if there are no known constraints.


Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.