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 allways 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 repondent 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
Created:
2. april 2003

Method Summary
 void deleteResponse(int questionNo)
          Deletes a response.
 long getCompletedDate()
          Gets the completed date
 int getCurrentResponse()
          Gets the current response.
 long getEntryDate()
          Gets the entry date
 java.lang.String getIpAddress()
          Gets the ip address.
 int getLastResponse()
          Gets the question number of last answered question.
 int getNextQuestion()
          Gets the number of the next question (after current response).
 long getRespondentId()
          Gets the respondent id
 Response getResponse(int questionNo)
          Gets a question response.
 long getSurveyId()
          Gets the survey id
 java.lang.String getTicket()
          Gets the ticket value
 java.lang.String getUserData(int index)
          Gets the userdata 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 setCurrentResponse(int currentResponse)
          Sets the current response.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getUserData

public java.lang.String getUserData(int index)
                             throws SurveySystemException
Gets the userdata 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 inluded 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.

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 ths)

Returns:
The ip address
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

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 .


Copyright © ObjectPlanet Inc. All Rights Reserved.

Built on May 7 2003