com.objectplanet.survey.plugin.api
Class Respondent

java.lang.Object
  com.objectplanet.survey.plugin.api.Respondent

public class Respondent
extends java.lang.Object

ATTENTION: This class is a facade for the system business Respondent. 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 always remember to call releaseBusinessObject() as soon as you are finished using them.

Respondent is an object that encapsulates information about users response to a survey like entry date, last response, completed date and so on. Flag isPersisted is set to true if respondent is saved in the storage.

To populate respondent object with user input (answers):
1) getResponse() to create new or get the existing response
2) set values to the response object (respondents answers)
3) call question.validate() method to validate the input
4) update current response: setCurrentResponse()
5) get the next question: getNextQuestion()
6) go to 1) and repeat until you reach the last question
7) store the respondent to the storage: SurveyManager.storeRespondent(). If the respondent has answered all the questions (getNextQuestion() returns -1), the completed date will be set and respondent will be removed from the cache.

Author:

Irina Brun, Torgeir Lund

Created:

2. april 2003

Method Summary

void	deleteResponse(int questionNo) Deletes a response.
java.lang.String	getAttribute(java.lang.String attributeName) Gets the value for a respondent attribute.
java.util.HashMap	getAttributes() Gets all the respondent attributes.
boolean	getAttributesExist() Returns true if one or more attributes exist for this respondent.
boolean	getBlocked() Get the flag that determines if the respondent is to be blocked from continuing the survey.
long	getCompletedDate() Gets the completed date
int	getCurrentResponse() Gets the current response.
long	getEntryDate() Gets the entry date
boolean	getFinishClicked() Get the flag that determines the finish-button was clicked in the survey.
long	getInviteeId() Gets the invitee id (if applicable)
java.lang.String	getIpAddress() Gets the ip address.
java.lang.String	getLanguageCode() Gets the languageCode for which language the respondent responded to the survey in.
int	getLastResponse() Gets the question number of last answered question.
int	getNextQuestion() Gets the number of the next question (after current response). If survey contains branch conditions some questions might be filtered out based on responses to the previous questions.
long	getRespondentId() Gets the respondent id
Response	getResponse(int questionNo) Gets a question response.
long	getSurveyId() Gets the survey id
java.lang.String	getThankYouNote() Gets the custom thank-you note for current respondent.
java.lang.String	getTicket() Gets the ticket value
java.lang.String	getUserData(int index) Gets the user data at a specified index.
boolean	hasBusinessObject() Check if this question has reference to the business Respondent object.
boolean	isFilteredOut(int questionNo) Check if question is filtered out by condition branching.
boolean	isPersisted() Returns true if respondent is persisted (some of the respondent information/responses are saved in the storage).
void	keepBusinessObject() Get and keep business object.
void	releaseBusinessObject() Release business object.
void	setAttribute(java.lang.String attributeName, java.lang.String attributeValue) Sets an attribute of the respondent object.
void	setBlocked(boolean blocked) Set this attribute to block the respondent from continue the survey.
void	setCurrentResponse(int currentResponse) Sets the current response.
void	setFinishClicked(boolean finishClicked) Sets the finishedClicked attribute.
void	setThankYouNote(java.lang.String thankYouNote) Sets the custom thank-you note for current respondent.

Methods inherited from class java.lang.Object

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

Method Detail

setAttribute

public void setAttribute(java.lang.String attributeName,
                         java.lang.String attributeValue)
                  throws SurveySystemException

Sets an attribute of the respondent object. Note that only attributes starting with opdata_() are allowed. Attributes with a different name will simply be ignored. When the respondent object is stored/updated the respondent attributes will be stored in the OPS_RespondentAttribute table in the database.

Parameters:

String - attributeName The attribute name

String - attributeValue The attribute value

Throws:

SurveySystemException

setFinishClicked

public void setFinishClicked(boolean finishClicked)
                      throws SurveySystemException

Sets the finishedClicked attribute. Setting this value to true simulates the clicking on the survey finish-button. CompletedDate will not be set unless this is set to true.

Parameters:

finishClicked - True to simulate clicking on finish button.

Throws:

SurveySystemException

setBlocked

public void setBlocked(boolean blocked)
                throws SurveySystemException

Set this attribute to block the respondent from continue the survey. It is mostly implemented as a convenient way to stop the respondent from a plugin.

Parameters:

blocked - True to block respondent, false otherwise.

Throws:

SurveySystemException

setThankYouNote

public void setThankYouNote(java.lang.String thankYouNote)
                     throws SurveySystemException

Sets the custom thank-you note for current respondent. If this is null, the default survey thank-you note is used. This is not persisted, and is to be used dynamically while a survey is running.

Parameters:

thankYouNote - The customized thank-you note.

Throws:

SurveySystemException

getAttribute

public java.lang.String getAttribute(java.lang.String attributeName)
                              throws SurveySystemException

Gets the value for a respondent attribute.

Parameters:

String - attributeName The attribute name

Returns:

String attributeValue The attribute value

Throws:

SurveySystemException

getAttributes

public java.util.HashMap getAttributes()
                                throws SurveySystemException

Gets all the respondent attributes.

Returns:

attributes The respondent attributes hashmap

Throws:

SurveySystemException

getAttributesExist

public boolean getAttributesExist()
                           throws SurveySystemException

Returns true if one or more attributes exist for this respondent.

Returns:

The attributesExist value

Throws:

SurveySystemException

getUserData

public java.lang.String getUserData(int index)
                             throws SurveySystemException

Gets the user data at a specified index. The user data is captured by the survey module if the parameters are included in the survey link, like this:

http://yourdomain.com/survey/s?s=10&u0=XXX&u1=YYY&u2=ZZZ

It is the "u0", "u1", etc, that is important. If these user specified parameters are included in the link to the survey, it is possible to retrieve the data in this method. The value for the "u0" parameter is retrieved by calling respondent.getUserData(0).

Parameters:

index - The index of the user data.

Returns:

The user data value, and the specified index.

Throws:

SurveySystemException - If an error occurs in the system.

setCurrentResponse

public void setCurrentResponse(int currentResponse)
                        throws java.lang.IllegalArgumentException,
                               SurveySystemException

Sets the current response. Should be updated as the respondent moves from question to question.

Parameters:

currentResponse - The number of the question the respondent is answering.

Throws:

java.lang.IllegalArgumentException - If invalid currentResponse

SurveySystemException - If an error occurs in the system.

getCompletedDate

public long getCompletedDate()
                      throws SurveySystemException

Gets the completed date

Returns:

The completed date value

Throws:

SurveySystemException - If an error occurs in the system.

getInviteeId

public long getInviteeId()
                  throws SurveySystemException

Gets the invitee id (if applicable)

Returns:

The invitee id

Throws:

SurveySystemException - If an error occurs in the system.

getCurrentResponse

public int getCurrentResponse()
                       throws SurveySystemException

Gets the current response.

Returns:

The number of the question the respondent is answering.

Throws:

SurveySystemException - If an error occurs in the system.

getEntryDate

public long getEntryDate()
                  throws SurveySystemException

Gets the entry date

Returns:

The entry date value

Throws:

SurveySystemException - If an error occurs in the system.

getIpAddress

public java.lang.String getIpAddress()
                              throws SurveySystemException

Gets the ip address. This is used to prevent multiple responses (cookies may also be used for this)

Returns:

The ip address

Throws:

SurveySystemException - If an error occurs in the system.

getLanguageCode

public java.lang.String getLanguageCode()
                                 throws SurveySystemException

Gets the languageCode for which language the respondent responded to the survey in. Note that the language code can change between answered questions, if the respondent selects another language in the dropdown list, but only the last selected language will be stored in the completed respondent object.

Returns:

The language code

Throws:

SurveySystemException - If an error occurs in the system.

getLastResponse

public int getLastResponse()
                    throws SurveySystemException

Gets the question number of last answered question.

Returns:

The last response value

Throws:

SurveySystemException - If an error occurs in the system.

getNextQuestion

public int getNextQuestion()
                    throws SurveySystemException

Gets the number of the next question (after current response).

If survey contains branch conditions some questions might be filtered out based on responses to the previous questions. This method returns the number of the next question the respondent should see/answer.

Returns:

The number of the next question or -1 if there are no more questions

Throws:

SurveySystemException - If an error occurs in the system.

getRespondentId

public long getRespondentId()

Gets the respondent id

Returns:

The respondent id

getBlocked

public boolean getBlocked()
                   throws SurveySystemException

Get the flag that determines if the respondent is to be blocked from continuing the survey. It is a convenient way to stop the respondent from continuing. This flag has nothing to do with respondent being blocked because he/she has responded before to the same survey. This flag is to be used beside all normal logic/functionality.

Returns:

True if respondent is blocked from continuing, otherwise false.

Throws:

SurveySystemException - If an error occurs in the system.

getFinishClicked

public boolean getFinishClicked()
                         throws SurveySystemException

Get the flag that determines the finish-button was clicked in the survey.

Returns:

True if the survey finish-button is clicked.

Throws:

SurveySystemException - If an error occurs in the system.

getThankYouNote

public java.lang.String getThankYouNote()
                                 throws SurveySystemException

Gets the custom thank-you note for current respondent. If this is null, the default survey thank-you note is used.

Returns:

The thank-you note value.

Throws:

SurveySystemException

getResponse

public Response getResponse(int questionNo)
                     throws java.lang.IllegalArgumentException,
                            SurveySystemException

Gets a question response. Will get a response previously created, for this question. If no response is found, an empty response is returned, ready to be filled with values. The isPersisted() method in the response object can be checked to see if the response was found or if an empty was returned.

Parameters:

questionNo - Question number of response to get

Returns:

The response

Throws:

java.lang.IllegalArgumentException - If illegal question number

SurveySystemException - If an error occurs in the system.

getSurveyId

public long getSurveyId()

Gets the survey id

Returns:

The survey id

getTicket

public java.lang.String getTicket()
                           throws SurveySystemException

Gets the ticket value

Returns:

The ticket value

Throws:

SurveySystemException - If an error occurs in the system.

isFilteredOut

public boolean isFilteredOut(int questionNo)
                      throws java.lang.IllegalArgumentException,
                             SurveySystemException

Check if question is filtered out by condition branching. If this method returns true, then the question is irrelevant and will be jumped over (the respondent will not see it) This value can be changed while respondent answering the survey.

Parameters:

questionNo - Question number

Returns:

True if the question is filtered out

Throws:

java.lang.IllegalArgumentException - If illegal question number

SurveySystemException - If any error occurs in the system.

isPersisted

public boolean isPersisted()
                    throws SurveySystemException

Returns true if respondent is persisted (some of the respondent information/responses are saved in the storage).

Returns:

The isPersisted value

Throws:

SurveySystemException - If an error occurs in the system.

deleteResponse

public void deleteResponse(int questionNo)
                    throws SurveySystemException

Deletes a response. Operation is persisted.

Parameters:

questionNo - Question number of response to remove.

Throws:

SurveySystemException - If an error occurs in the system.

hasBusinessObject

public boolean hasBusinessObject()

Check if this question has reference to the business Respondent 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 .