com.objectplanet.survey.plugin.api
Class Question

java.lang.Object
  |
  +--com.objectplanet.survey.plugin.api.Question
Direct Known Subclasses:
QuestionDropdown, QuestionMatrix, QuestionMultiple, QuestionNumeric, QuestionRating

public class Question
extends java.lang.Object

ATTENTION: This class is a facade for the system business Question. To improve performance you can force it to keep the reference to the business object by calling keepBusinessObject() . Keeping references to objects may cause inconsistencies in the system, so allways remember to call releaseBusinessObject() as soon as you are finished using them.

Class Question encapsulates question data.
Question types implemented as subclasses of Question. A question can be one of the following types:


In addition to type input, a question can have other forms of input:
Input from respondents must be validated. Method validate() performs this operation and should be called after each response.

Plugin api for branch conditions is not yet implemented.

Author:
Irina Brun
Created:
21. march 2003

Field Summary
static int ESSAY_FIELD_CHECKBOX
          Checkbox essay field type
static int ESSAY_FIELD_DROPDOWN
          Dropdown essay field type
static int ESSAY_FIELD_NUMERIC_DEC
          Numeric decimal essay field type
static int ESSAY_FIELD_NUMERIC_INT
          Numeric integer essay field type
static int ESSAY_FIELD_TEXT
          Text input essay field type
static int ESSAYFIELD_LENGTH
          Essay field total length
static int QUESTION_DROPDOWN
          Dropdown question type
static int QUESTION_MATRIX
          Matrix question type
static int QUESTION_MULTIPLE
          Multiple choice question type
static int QUESTION_NO_TYPE
          No question type (essay fields or free text is usually used for input)
static int QUESTION_NUMERIC
          Numeric question type
static int QUESTION_RATING
          Rating question type
static java.lang.String TAG_END
          Essay field end
static java.lang.String TAG_START
          Essay field start
 
Method Summary
 void addEssayFieldCheckbox(int index)
          Adds an essay field of type checkbox.
 void addEssayFieldDecimal(int index, int fieldSize, java.lang.String errorMsg)
          Adds an essay field of type numeric decimal.
 void addEssayFieldDropdown(int index, java.lang.String label, java.lang.String items, boolean sortOn)
          Adds an essay field of type dropdown.
 void addEssayFieldInteger(int index, int fieldSize, java.lang.String errorMsg)
          Adds an essay field of type numeric integer.
 void addEssayFieldText(int index, int fieldSize)
          Adds an essay field of type text.
 void deleteEssayField(int essayFieldIndex)
          Delete essay field.
 void deleteValidator(int type)
          Delete validator.
 void deleteValidator(int type, int essayFieldIndex)
          Delete essay field validator.
 void deleteValidator(int type, int columnPosition, int rowPosition)
          Delete matrix cell validator.
 java.lang.String getDisplayNo()
          Gets the display number attribute of the question.
 int getEssayFieldCount()
          Gets the number of essay fields
 java.lang.String[] getEssayFieldDropdownItems(int essayFieldIndex)
          Get dropdown items of essay field, one per line.
 java.lang.String getEssayFieldDropdownLabel(int essayFieldIndex)
          Get dropdown label of essay field.
 boolean getEssayFieldDropdownSortOn(int essayFieldIndex)
          Get dropdown essay field sortOn attribute .
 int getEssayFieldSize(int essayFieldIndex)
          Get essay field size.
 int getEssayFieldType(int essayFieldIndex)
          Get essay field type..
 int getFreeTextColumns()
          Gets the number of columns in the free-text field
 java.lang.String getFreeTextLabel()
          Gets the label of the free-text field
 int getFreeTextMaxLength()
          Gets the max allowed length (to type in) of the free-text field.
 int getFreeTextRows()
          Gets the number of rows in the free-text field
 long getQuestionId()
          Gets the question Id.
 java.lang.String getQuestionLayout()
          Gets the question layout.
 java.lang.String getQuestionText()
          Gets the question text.
 int getQuestionType()
          Gets the questionType attribute of the Question.
 java.lang.String getTextAfter()
          Gets the textAfter attribute of the Question.
 java.lang.String getTextBefore()
          Gets the text-before attribute of the question.
 java.lang.String getValidatorErrorMessage(int type)
          Gets error message for validator.
 java.lang.String getValidatorErrorMessage(int type, int essayFieldIndex)
          Gets error message for essay field validator.
 java.lang.String getValidatorErrorMessage(int type, int columnPosition, int rowPosition)
          Gets error message for matrix cell validator.
 java.lang.String getValidatorParameter(int type)
          Gets the validator parameter.
 java.lang.String getValidatorParameter(int type, int essayFieldIndex)
          Gets the essay field validator parameter.
 java.lang.String getValidatorParameter(int type, int columnPosition, int rowPosition)
          Gets the matrix cell validator parameter.
 boolean hasBusinessObject()
          Check if this question has reference to the business Question object.
 boolean isFreeTextOn()
          Gets the freeTextOn attribute of the question
 boolean isValidatorOn(int type)
          Check if validator is on.
 boolean isValidatorOn(int type, int essayFieldIndex)
          Check if essay field validator is on.
 boolean isValidatorOn(int type, int columnPosition, int rowPosition)
          Check if matrix cell validator is on.
 void keepBusinessObject()
          Get and keep business object.
 void releaseBusinessObject()
          Release business object.
 void setDisplayNo(java.lang.String displayNo)
          The display number is specified by survey creator/admin.
 void setFreeTextColumns(int freeTextCols)
          Sets the number of columns in the free-text field
 void setFreeTextLabel(java.lang.String freeTextLabel)
          Sets the label for the free-text field
 void setFreeTextMaxLength(int freeTextMaxLength)
          Sets the max length allowed to type in the free text field.
 void setFreeTextOn(boolean freeTextOn)
          Sets the freeTextOn attribute of the question
 void setFreeTextRows(int freeTextRows)
          Sets the number of rows in the free-text field
 void setQuestionLayout(java.lang.String questionLayout)
          Sets the question layout attribute of the question.
 void setQuestionText(java.lang.String questionText)
          Sets the question text.
 void setTextAfter(java.lang.String textAfter)
          Sets the text-after attribute of the question.
 void setTextBefore(java.lang.String setTextBefore)
          Sets the text-before attribute of the question.
 void setValidator(int type, java.lang.String errorMessage, java.lang.String parameter)
          Sets the validator.
 void setValidator(int type, java.lang.String errorMessage, java.lang.String parameter, int essayFieldIndex)
          Sets the essay field validator.
 void setValidator(int type, java.lang.String errorMessage, java.lang.String parameter, int columnPosition, int rowPosition)
          Sets the matrix cell validator.
 boolean validate(Response response)
          Validates a response.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ESSAYFIELD_LENGTH

public static final int ESSAYFIELD_LENGTH
Essay field total length

See Also:
Constant Field Values

ESSAY_FIELD_CHECKBOX

public static final int ESSAY_FIELD_CHECKBOX
Checkbox essay field type

See Also:
Constant Field Values

ESSAY_FIELD_DROPDOWN

public static final int ESSAY_FIELD_DROPDOWN
Dropdown essay field type

See Also:
Constant Field Values

ESSAY_FIELD_NUMERIC_DEC

public static final int ESSAY_FIELD_NUMERIC_DEC
Numeric decimal essay field type

See Also:
Constant Field Values

ESSAY_FIELD_NUMERIC_INT

public static final int ESSAY_FIELD_NUMERIC_INT
Numeric integer essay field type

See Also:
Constant Field Values

ESSAY_FIELD_TEXT

public static final int ESSAY_FIELD_TEXT
Text input essay field type

See Also:
Constant Field Values

QUESTION_DROPDOWN

public static final int QUESTION_DROPDOWN
Dropdown question type

See Also:
Constant Field Values

QUESTION_MATRIX

public static final int QUESTION_MATRIX
Matrix question type

See Also:
Constant Field Values

QUESTION_MULTIPLE

public static final int QUESTION_MULTIPLE
Multiple choice question type

See Also:
Constant Field Values

QUESTION_NO_TYPE

public static final int QUESTION_NO_TYPE
No question type (essay fields or free text is usually used for input)

See Also:
Constant Field Values

QUESTION_NUMERIC

public static final int QUESTION_NUMERIC
Numeric question type

See Also:
Constant Field Values

QUESTION_RATING

public static final int QUESTION_RATING
Rating question type

See Also:
Constant Field Values

TAG_END

public static final java.lang.String TAG_END
Essay field end

See Also:
Constant Field Values

TAG_START

public static final java.lang.String TAG_START
Essay field start

See Also:
Constant Field Values
Method Detail

setDisplayNo

public void setDisplayNo(java.lang.String displayNo)
                  throws LockException,
                         RespondentsExistException,
                         SurveySecurityException,
                         SurveySystemException
The display number is specified by survey creator/admin. This attribute is displayed instead of the question number, if Survey attribute dislpayQuestionNo is set to DISPLAY_QUESTIONNO_DEFINED

Parameters:
displayNo - The new display number
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setFreeTextColumns

public void setFreeTextColumns(int freeTextCols)
                        throws LockException,
                               RespondentsExistException,
                               SurveySecurityException,
                               SurveySystemException
Sets the number of columns in the free-text field

Parameters:
freeTextCols - The number of columns
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setFreeTextLabel

public void setFreeTextLabel(java.lang.String freeTextLabel)
                      throws LockException,
                             RespondentsExistException,
                             SurveySecurityException,
                             SurveySystemException
Sets the label for the free-text field

Parameters:
freeTextLabel - The new free-text label
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setFreeTextMaxLength

public void setFreeTextMaxLength(int freeTextMaxLength)
                          throws LockException,
                                 RespondentsExistException,
                                 SurveySecurityException,
                                 SurveySystemException
Sets the max length allowed to type in the free text field.

Parameters:
freeTextMaxLength - The max length of free-text field.
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setFreeTextOn

public void setFreeTextOn(boolean freeTextOn)
                   throws LockException,
                          RespondentsExistException,
                          SurveySecurityException,
                          SurveySystemException
Sets the freeTextOn attribute of the question

Parameters:
freeTextOn - The new freeTextOn value
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setFreeTextRows

public void setFreeTextRows(int freeTextRows)
                     throws LockException,
                            RespondentsExistException,
                            SurveySecurityException,
                            SurveySystemException
Sets the number of rows in the free-text field

Parameters:
freeTextRows - The new number of free text rows
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setQuestionLayout

public void setQuestionLayout(java.lang.String questionLayout)
                       throws LockException,
                              RespondentsExistException,
                              SurveySecurityException,
                              SurveySystemException
Sets the question layout attribute of the question. Question text may be placed above or to the left of question input fields.

Parameters:
questionLayout - The new questionLayout value. "horizontal" / "vertical"
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setQuestionText

public void setQuestionText(java.lang.String questionText)
                     throws LockException,
                            RespondentsExistException,
                            SurveySecurityException,
                            SurveySystemException
Sets the question text.

Parameters:
questionText - The new question text
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setTextAfter

public void setTextAfter(java.lang.String textAfter)
                  throws LockException,
                         RespondentsExistException,
                         SurveySecurityException,
                         SurveySystemException
Sets the text-after attribute of the question. Makes it possible to have section-headings, footnotes, separators etc between questions.

Parameters:
textAfter - The new textAfter
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setTextBefore

public void setTextBefore(java.lang.String setTextBefore)
                   throws LockException,
                          RespondentsExistException,
                          SurveySecurityException,
                          SurveySystemException
Sets the text-before attribute of the question. For inserting section-headings between questions, horizontal lines etc.

Parameters:
setTextBefore - The new textBefore value
Throws:
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.

setValidator

public void setValidator(int type,
                         java.lang.String errorMessage,
                         java.lang.String parameter)
                  throws LockException,
                         RespondentsExistException,
                         SurveySecurityException,
                         SurveySystemException,
                         java.lang.IllegalArgumentException
Sets the validator. Use this method for all validator types except essay field and matrix cell validators.

Parameters:
type - Validator type. See ValidatorType
errorMessage - Error message to show to the respondent if the input is incorrect.
parameter - Validator parameter. See comment for the validator type.
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

setValidator

public void setValidator(int type,
                         java.lang.String errorMessage,
                         java.lang.String parameter,
                         int essayFieldIndex)
                  throws LockException,
                         RespondentsExistException,
                         SurveySecurityException,
                         SurveySystemException,
                         java.lang.IllegalArgumentException
Sets the essay field validator.

Parameters:
type - Essay field validator type. See ValidatorType
errorMessage - Error message to show to the respondent if the input is incorrect.
parameter - Validator parameter. See comment for the validator type.
essayFieldIndex - Essay field position, starts at 0.
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

setValidator

public void setValidator(int type,
                         java.lang.String errorMessage,
                         java.lang.String parameter,
                         int columnPosition,
                         int rowPosition)
                  throws LockException,
                         RespondentsExistException,
                         SurveySecurityException,
                         SurveySystemException,
                         java.lang.IllegalArgumentException
Sets the matrix cell validator.

Parameters:
type - Matrix cell validator type. See ValidatorType
errorMessage - Error message to show to the respondent if the input is incorrect.
parameter - Validator parameter. See comment for the validator type.
columnPosition - Matrix cell column position.
rowPosition - Matrix cell row position.
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySecurityException - Thrown if the user is not authorized to call this method.
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

getDisplayNo

public java.lang.String getDisplayNo()
                              throws SurveySystemException
Gets the display number attribute of the question. Survey administrator can specify what question number to be displayed, instead of the sequential questionNo.

Returns:
The display number
Throws:
SurveySystemException - If an error occurs in the system.

getEssayFieldCount

public int getEssayFieldCount()
                       throws SurveySystemException
Gets the number of essay fields

Returns:
The number of essay fields
Throws:
SurveySystemException - If an error occurs in the system.

getEssayFieldDropdownItems

public java.lang.String[] getEssayFieldDropdownItems(int essayFieldIndex)
                                              throws SurveySystemException
Get dropdown items of essay field, one per line. Applicable for essay fields of type ESSAY_FIELD_DROPDOWN.

Parameters:
essayFieldIndex - Index of the essay field. (If you have 5 essay fields, essayFieldIndex can be from 0 to 4)
Returns:
The dropdown items for essay field or null.
Throws:
SurveySystemException - If an error occurs in the system.

getEssayFieldDropdownLabel

public java.lang.String getEssayFieldDropdownLabel(int essayFieldIndex)
                                            throws SurveySystemException
Get dropdown label of essay field. Applicable for essay fields of type ESSAY_FIELD_DROPDOWN.

Parameters:
essayFieldIndex - Index of the essay field. (If you have 5 essay fields, essayFieldIndex can be from 0 to 4)
Returns:
The dropdown label for essay field or null.
Throws:
SurveySystemException - If an error occurs in the system.

getEssayFieldDropdownSortOn

public boolean getEssayFieldDropdownSortOn(int essayFieldIndex)
                                    throws SurveySystemException
Get dropdown essay field sortOn attribute . Applicable for essay fields of type ESSAY_FIELD_DROPDOWN.

Parameters:
essayFieldIndex - Index of the essay field. (If you have 5 essay fields, essayFieldIndex can be from 0 to 4)
Returns:
The dropdown sort on attribute or false.
Throws:
SurveySystemException - If an error occurs in the system.

getEssayFieldSize

public int getEssayFieldSize(int essayFieldIndex)
                      throws SurveySystemException
Get essay field size. Applicable for essay fields of type ESSAY_FIELD_TEXT, ESSAY_FIELD_NUMERIC_INT and ESSAY_FIELD_NUMERIC_DEC.

Parameters:
essayFieldIndex - Index of the essay field. (If you have 5 essay fields, essayFieldIndex can be from 0 to 4)
Returns:
The essay field size.
Throws:
SurveySystemException - If an error occurs in the system.

getEssayFieldType

public int getEssayFieldType(int essayFieldIndex)
                      throws SurveySystemException
Get essay field type..

Parameters:
essayFieldIndex - Index of the essay field. (If you have 5 essay fields, essayFieldIndex can be from 0 to 4)
Returns:
The essay field type. One of the constants above.
Throws:
SurveySystemException - If an error occurs in the system.

getFreeTextColumns

public int getFreeTextColumns()
                       throws SurveySystemException
Gets the number of columns in the free-text field

Returns:
The free-text field column count
Throws:
SurveySystemException - If an error occurs in the system.

getFreeTextLabel

public java.lang.String getFreeTextLabel()
                                  throws SurveySystemException
Gets the label of the free-text field

Returns:
The free-text field label
Throws:
SurveySystemException - If an error occurs in the system.

getFreeTextMaxLength

public int getFreeTextMaxLength()
                         throws SurveySystemException
Gets the max allowed length (to type in) of the free-text field.

Returns:
The max length
Throws:
SurveySystemException - If an error occurs in the system.

getFreeTextRows

public int getFreeTextRows()
                    throws SurveySystemException
Gets the number of rows in the free-text field

Returns:
The free-text field row count
Throws:
SurveySystemException - If an error occurs in the system.

getQuestionId

public long getQuestionId()
                   throws SurveySystemException
Gets the question Id. The question id is the same unique value as stored in the database.

Returns:
The question id
Throws:
SurveySystemException - If an error occurs in the system.

getQuestionLayout

public java.lang.String getQuestionLayout()
                                   throws SurveySystemException
Gets the question layout. Question text may be placed above or to the left of question input fields.

Returns:
The question layout. "horizontal" / "vertical"
Throws:
SurveySystemException - If an error occurs in the system.

getQuestionText

public java.lang.String getQuestionText()
                                 throws SurveySystemException
Gets the question text.

Returns:
The question text
Throws:
SurveySystemException - If an error occurs in the system.

getQuestionType

public int getQuestionType()
                    throws SurveySystemException
Gets the questionType attribute of the Question. Question type is "rating", "numeric" etc.

Returns:
The question type. One of the constants above
Throws:
SurveySystemException - If an error occurs in the system.

getTextAfter

public java.lang.String getTextAfter()
                              throws SurveySystemException
Gets the textAfter attribute of the Question. For making section headers, separators etc.

Returns:
The text after
Throws:
SurveySystemException - If an error occurs in the system.

getTextBefore

public java.lang.String getTextBefore()
                               throws SurveySystemException
Gets the text-before attribute of the question. For making section headers, separators etc.

Returns:
The text before
Throws:
SurveySystemException - If an error occurs in the system.

getValidatorErrorMessage

public java.lang.String getValidatorErrorMessage(int type)
                                          throws SurveySystemException,
                                                 java.lang.IllegalArgumentException
Gets error message for validator. Use this method for all validator types except essay field and matrix cell validators.

Parameters:
type - Validator type. See ValidatorType
Returns:
The error message or null if no validator of this type is found.
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.

getValidatorErrorMessage

public java.lang.String getValidatorErrorMessage(int type,
                                                 int essayFieldIndex)
                                          throws SurveySystemException,
                                                 java.lang.IllegalArgumentException
Gets error message for essay field validator.

Parameters:
type - Essay field validator type. See ValidatorType
essayFieldIndex - Position of the essay field. Starts at 0.
Returns:
The error message or null if no validator of this type is found for the essay field
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.

getValidatorErrorMessage

public java.lang.String getValidatorErrorMessage(int type,
                                                 int columnPosition,
                                                 int rowPosition)
                                          throws SurveySystemException,
                                                 java.lang.IllegalArgumentException
Gets error message for matrix cell validator.

Parameters:
type - Matrix cell validator type. See ValidatorType
columnPosition - Matrix cell column position.
rowPosition - Matrix cell row position.
Returns:
The error message or null if no validator of this type is found for the cell
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.

getValidatorParameter

public java.lang.String getValidatorParameter(int type)
                                       throws SurveySystemException,
                                              java.lang.IllegalArgumentException
Gets the validator parameter. Use this method for all validator types except essay field and matrix cell validators.

Parameters:
type - Validator type. See ValidatorType
Returns:
The validator parameter or null if no parameter exists.
Throws:
java.lang.IllegalArgumentException - If invalid type.
SurveySystemException - If an error occurs in the system.

getValidatorParameter

public java.lang.String getValidatorParameter(int type,
                                              int essayFieldIndex)
                                       throws SurveySystemException,
                                              java.lang.IllegalArgumentException
Gets the essay field validator parameter.

Parameters:
type - Essay field validator type. See ValidatorType
essayFieldIndex - Position of the essay field
Returns:
The validator parameter or null if no parameter of this type exists for the essay field.
Throws:
java.lang.IllegalArgumentException - If invalid type/position.
SurveySystemException - If an error occurs in the system.

getValidatorParameter

public java.lang.String getValidatorParameter(int type,
                                              int columnPosition,
                                              int rowPosition)
                                       throws SurveySystemException,
                                              java.lang.IllegalArgumentException
Gets the matrix cell validator parameter.

Parameters:
type - Matrix cell validator type. See ValidatorType
columnPosition - Matrix cell column position
rowPosition - Matrix row column position
Returns:
The validator parameter or null if no parameter of this type exists for the matrix cell.
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.

isFreeTextOn

public boolean isFreeTextOn()
                     throws SurveySystemException
Gets the freeTextOn attribute of the question

Returns:
The freeTextOn value
Throws:
SurveySystemException - If an error occurs in the system.

isValidatorOn

public boolean isValidatorOn(int type)
                      throws SurveySystemException,
                             java.lang.IllegalArgumentException
Check if validator is on. Use this method for all validator types except essay field and matrix cell validators.

Parameters:
type - Validator type. See ValidatorType
Returns:
The validatorOn value
Throws:
java.lang.IllegalArgumentException - If invalid validator type.
SurveySystemException - If an error occurs in the system.

isValidatorOn

public boolean isValidatorOn(int type,
                             int essayFieldIndex)
                      throws SurveySystemException,
                             java.lang.IllegalArgumentException
Check if essay field validator is on.

Parameters:
type - Essay field validator type. See ValidatorType
essayFieldIndex - Essay field index (starts at 0)
Returns:
The validatorOn value
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.

isValidatorOn

public boolean isValidatorOn(int type,
                             int columnPosition,
                             int rowPosition)
                      throws SurveySystemException,
                             java.lang.IllegalArgumentException
Check if matrix cell validator is on.

Parameters:
type - Matrix cell validator type. See ValidatorType
columnPosition - Matrix cell column position, starts at 0
rowPosition - Matrix cell row position, starts at 0
Returns:
The validatorOn value
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.

addEssayFieldCheckbox

public void addEssayFieldCheckbox(int index)
                           throws LockException,
                                  SurveySystemException,
                                  SurveySecurityException,
                                  RespondentsExistException,
                                  java.lang.IllegalArgumentException
Adds an essay field of type checkbox. Read about essay fields .

Parameters:
index - Position in the question text where the essay field will be inserted.
Throws:
SurveySystemException - If an error occurs in the system.
java.lang.IllegalArgumentException - If illegal index.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

addEssayFieldDecimal

public void addEssayFieldDecimal(int index,
                                 int fieldSize,
                                 java.lang.String errorMsg)
                          throws LockException,
                                 SurveySystemException,
                                 SurveySecurityException,
                                 RespondentsExistException,
                                 java.lang.IllegalArgumentException
Adds an essay field of type numeric decimal. Read about essay fields .

Parameters:
index - Position in the question text where the essay field will be inserted.
fieldSize - The size of the text field.
errorMsg - Error message to show to the respondent if the response is not a invalid double.
Throws:
SurveySystemException - If an error occurs in the system.
java.lang.IllegalArgumentException - If illegal index or errorMsg is null or empty.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

addEssayFieldDropdown

public void addEssayFieldDropdown(int index,
                                  java.lang.String label,
                                  java.lang.String items,
                                  boolean sortOn)
                           throws LockException,
                                  SurveySecurityException,
                                  RespondentsExistException,
                                  SurveySystemException
Adds an essay field of type dropdown. Read about essay fields .

Parameters:
index - Position in the question text where the essay field will be inserted.
label - The displayed label of the dropdown list when no items are selected.
items - Dropdown items as String one per line. (separated by /n/r)
sortOn - True if items should be alphabetically sorted.
Throws:
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

addEssayFieldInteger

public void addEssayFieldInteger(int index,
                                 int fieldSize,
                                 java.lang.String errorMsg)
                          throws LockException,
                                 SurveySecurityException,
                                 RespondentsExistException,
                                 SurveySystemException,
                                 java.lang.IllegalArgumentException
Adds an essay field of type numeric integer. Read about essay fields .

Parameters:
index - Position in the question text where the essay field will be inserted.
fieldSize - The size of the text field.
errorMsg - Error message to show to the respondent if the response is not a invalid integer.
Throws:
SurveySystemException - If an error occurs in the system.
java.lang.IllegalArgumentException - If illegal index or errorMsg is null or empty.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

addEssayFieldText

public void addEssayFieldText(int index,
                              int fieldSize)
                       throws LockException,
                              SurveySecurityException,
                              RespondentsExistException,
                              SurveySystemException,
                              java.lang.IllegalArgumentException
Adds an essay field of type text. Read about essay fields .

Parameters:
index - Position in the question text where the essay field will be inserted.
fieldSize - The size of the text field.
Throws:
SurveySystemException - If an error occurs in the system.
java.lang.IllegalArgumentException - If illegal index.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

deleteEssayField

public void deleteEssayField(int essayFieldIndex)
                      throws LockException,
                             SurveySecurityException,
                             RespondentsExistException,
                             SurveySystemException
Delete essay field. Validators for the field will be automatically deleted.

Parameters:
essayFieldIndex - Index of the essay field. (If you have 5 essay fields, essayFieldIndex can be from 0 to 4)
Throws:
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.

deleteValidator

public void deleteValidator(int type)
                     throws LockException,
                            RespondentsExistException,
                            SurveySystemException,
                            SurveySecurityException,
                            java.lang.IllegalArgumentException
Delete validator. Use this method for all validator types except essay field and matrix cell validators.

Parameters:
type - Validator type. See ValidatorType
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.

deleteValidator

public void deleteValidator(int type,
                            int essayFieldIndex)
                     throws LockException,
                            RespondentsExistException,
                            SurveySystemException,
                            SurveySecurityException,
                            java.lang.IllegalArgumentException
Delete essay field validator.

Parameters:
type - Essay field validator type. See ValidatorType
essayFieldIndex - Position of the essay field. Starts at 0.
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.

deleteValidator

public void deleteValidator(int type,
                            int columnPosition,
                            int rowPosition)
                     throws LockException,
                            RespondentsExistException,
                            SurveySystemException,
                            SurveySecurityException,
                            java.lang.IllegalArgumentException
Delete matrix cell validator.

Parameters:
type - Matrix cell validator type. See ValidatorType
columnPosition - Matrix cell column position.
rowPosition - Matrix cell row position.
Throws:
java.lang.IllegalArgumentException - If invalid parameters.
SurveySystemException - If an error occurs in the system.
LockException - Thrown if the survey is locked and can't be edited. Not yet implemented. Use survey.isLocked() to be sure that the survey can be updated.
RespondentsExistException - Thrown if the survey has responses and can't be edited. Not yet implemented. Use survey.hasRespondents() to be sure that the survey can be updated.
SurveySecurityException - Thrown if the user is not authorized to call this method.

hasBusinessObject

public boolean hasBusinessObject()
Check if this question has reference to the business Question object. See ATTENTION .

Returns:
True/false

keepBusinessObject

public void keepBusinessObject()
                        throws SurveySystemException
Get and keep business object. See ATTENTION .

Throws:
SurveySystemException - If an error occurs in the system.

releaseBusinessObject

public void releaseBusinessObject()
Release business object. See ATTENTION .


validate

public boolean validate(Response response)
                 throws SurveySystemException
Validates a response. This method MUST be called after each response. Returns true if all values in the response object are valid.

Parameters:
response - Responde to this question that should be validated.
Returns:
Returns true if all values in the response object are valid.
Throws:
SurveySystemException - If an error occurs in the system.

Copyright © ObjectPlanet Inc. All Rights Reserved.

Built on May 7 2003