Class 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
  • Field Details

    • value

      protected Properties value
      The current (default or latest) response to this question.
  • Constructor Details

    • PropertiesQuestion

      protected PropertiesQuestion(Interview interview, 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, String tag, 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:
      NullPointerException - if choices is null
    • PropertiesQuestion

      protected PropertiesQuestion(Interview interview, String tag, 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:
      NullPointerException - if choices is null
  • Method Details

    • load

      protected static Properties load(String s)
    • setProperties

      protected void setProperties(Properties props)
      The current value will be set to all false;
      Parameters:
      props - The set of names for the choices for this question.
      Throws:
      NullPointerException - if choices is null
      See Also:
    • setKeys

      protected void setKeys(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:
      NullPointerException - if choices is null
      See Also:
    • getKeys

      public 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:
    • getDefaultValue

      public Properties getDefaultValue()
      Get the default response for this question.
      Returns:
      the default response for this question.
      See Also:
    • setDefaultValue

      public void setDefaultValue(Properties props)
      Set the default response for this question, used by the clear method.
      Parameters:
      props - the default response for this question.
      See Also:
    • getValue

      public Properties getValue()
      Get the current (default or latest) response to this question.
      Returns:
      The current value - a cloned copy.
      Throws:
      IllegalStateException - if no choices have been set, defining the set of responses to this question
      See Also:
    • setValue

      public void setValue(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:
    • setValue

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

      public 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:
    • getStringValue

      public 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:
    • setValue

      public void setValue(String key, 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.
      NullPointerException - if either parameter is null
      Interview.Fault - if the specified key does not exist in the question
      See Also:
    • 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(Map<String,String> data)
      Load the value for this question from a dictionary, using the tag as the key.
      Overrides:
      load in class Question
      Parameters:
      data - The map from which to load the value for this question.
    • save

      protected void save(Map<String,String> 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(String key)
      Determine if a value is read-only.
    • isEntryVisible

      public boolean isEntryVisible(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 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 String isValueValid(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:
    • updateProperties

      public void updateProperties(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:
      IllegalArgumentException - If a property in props does not exist.
    • updateProperty

      public void updateProperty(String key, String val)
      Update the given property. New properties cannot be added this way.
      Parameters:
      key - Property to update.
      val - Value for the property.
      Throws:
      IllegalArgumentException - If the property does not exist.
    • createGroup

      public void createGroup(String name)
      Create a new group.
      Throws:
      IllegalStateException - If the group requested already exists.
    • setGroup

      public void setGroup(String group, 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:
      IllegalArgumentException - If an attempt is made to add to a group which does not exist.
      IllegalStateException - If an attempt is made to group a key which is not present.
      See Also:
    • setGroup

      public void setGroup(String group, String... keys)
    • getGroups

      public 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:
    • getGroup

      public String[][] getGroup(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:
    • getUngrouped

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

      public String getGroupDisplayName(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 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 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(String key, PropertiesQuestion.ValueConstraints c)
      Apply constraints to a value.
      Throws:
      IllegalArgumentException - If the key supplied does not exist in the current data.
      See Also:
    • getConstraintKeyFromRow

      public String getConstraintKeyFromRow(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
    • getKeyPropertyName

      public String getKeyPropertyName(String key)
      Get the property name for displayed key value in the table
      Parameters:
      key - value of the key in the table
      Returns:
      key or the property name for the key
    • getPresentationKeys

      public Map<String,String> getPresentationKeys()
      Returns the localized key values to display
    • getConstraints

      public PropertiesQuestion.ValueConstraints getConstraints(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.