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 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)
      • 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.
      • 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
      • getKeyPropertyName

        public java.lang.String getKeyPropertyName​(java.lang.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 java.util.HashMap getPresentationKeys()
        Returns the localized key values to display
      • 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.