com.objectplanet.survey.plugin.api
Class SurveyManager

java.lang.Object
  |
  +--com.objectplanet.survey.plugin.api.SurveyManager

public class SurveyManager
extends java.lang.Object

Encapsulates functionality to manage folders, surveys and respondents.

Author:
Irina Brun

Constructor Summary
SurveyManager()
           
 
Method Summary
static Folder createFolder(User user, long parentFolderId, java.lang.String folderName, java.lang.String folderDescription)
          Creates a folder.
static Respondent createRespondent(long surveyId)
          Create a new respondent object.
static Survey createSurvey(User user, long folderId)
          Creates a survey.
static void deleteFolder(User user, long folderId)
          Delete a folder by id.
static void deleteIncompleteRespondents(User user, long surveyId)
          Removes all incomplete respondents for the survey permanently.
static void deleteRespondent(User user, long respondentId, long surveyId)
          Removes a respondent permanently.
static void deleteRespondents(User user, long surveyId)
          Removes all respondents for the survey permanently.
static void deleteSurvey(User user, long surveyId)
          Delete a survey by survey id.
static Folder getFolder(User user, long folderId)
          Get a folder by id.
static Respondent getRespondentForAdmin(long respondentId, long surveyId)
          Get a respondent by id.
static Respondent getRespondentForSurvey(long respondentId, long surveyId)
          Get a respondent by id.
static java.util.ArrayList getRespondentIds(User user, long surveyId, boolean incompleted)
          Get all respondent ids for this survey.
static Survey getSurvey(User user, long surveyId)
          Gets the survey by id.
static void storeRespondent(long respondentId, long surveyId)
          Save respondent to the storage.
static void updateSurvey(User user, long surveyId)
          Updates a survey in the storage.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SurveyManager

public SurveyManager()
Method Detail

getFolder

public static Folder getFolder(User user,
                               long folderId)
                        throws SurveySystemException,
                               SurveySecurityException
Get a folder by id.

Parameters:
user - User
folderId - Folder id to get
Returns:
The folder value
Throws:
SurveySystemException - If an error occurs in the system.
SurveySecurityException - Thrown if the user doesn't have read access to the folder.

getRespondentForAdmin

public static Respondent getRespondentForAdmin(long respondentId,
                                               long surveyId)
                                        throws SurveySystemException
Get a respondent by id. Use this method when respondent object is needed for administration module (usually for reading respondent info/responses). Return null if respondent not found.

The only difference between getRespondentForSurvey() and getRespondentForAdmin() is that in the first case the respondent will be processed by 'cleaner-thread', which saves timed-out respondents to the storage and removes them from the cache. In the second case, the respondent will be ignored by the cleaner.

Parameters:
respondentId - Respondent id
surveyId - Survey id
Returns:
The respondent object
Throws:
SurveySystemException - If an error occurs in the system.

getRespondentForSurvey

public static Respondent getRespondentForSurvey(long respondentId,
                                                long surveyId)
                                         throws SurveySystemException
Get a respondent by id. Use this method when respondent object is needed for survey module (for adding/editing responses). Return null if respondent not found.

The only difference between getRespondentForSurvey() and getRespondentForAdmin() is that in the first case the respondent will be processed by 'cleaner-thread', which saves timed-out respondents to the storage and removes them from the cache. In the second case, the respondent will be ignored by the cleaner.

Parameters:
respondentId - Respondent id
surveyId - Survey id
Returns:
The respondent object
Throws:
SurveySystemException - If an error occurs in the system.

getRespondentIds

public static java.util.ArrayList getRespondentIds(User user,
                                                   long surveyId,
                                                   boolean incompleted)
                                            throws SurveySystemException,
                                                   SurveySecurityException
Get all respondent ids for this survey. Returns ArrayList respondent ids (as Long).

Parameters:
user - User
surveyId - Survey id
incompleted - False if incompleted responses are not included
Returns:
ArrayList of Long objects(respondent ids)
Throws:
SurveySystemException - If an error occurs in the system.
SurveySecurityException - If no access

getSurvey

public static Survey getSurvey(User user,
                               long surveyId)
                        throws SurveySecurityException,
                               SurveySystemException
Gets the survey by id.

Parameters:
user - User
surveyId - Survey id
Returns:
The survey
Throws:
SurveySecurityException - Thrown if the user doesn't have read access to the survey.
SurveySystemException - If an error occurs in the system.

createFolder

public static Folder createFolder(User user,
                                  long parentFolderId,
                                  java.lang.String folderName,
                                  java.lang.String folderDescription)
                           throws SurveySecurityException,
                                  SurveySystemException
Creates a folder. The folder will be empty, with just the id set. Set folder attributes and call updateFolder() method to save them to the storage.
Require permission to create sub-folders in the parent folder. The creator will get full access to the folder.

Parameters:
user - Current user
parentFolderId - Folder id where the new folder will be placed (parent folder)
folderName - New folder name
folderDescription - New folder description
Returns:
Folder proxy object, representing the folder
Throws:
SurveySecurityException - If the user is unauthorized to create folders in the parent folder.
SurveySystemException - If any error occurs in the system.

createRespondent

public static Respondent createRespondent(long surveyId)
                                   throws LockException,
                                          SurveySystemException
Create a new respondent object. Use this method when you want to answer to the survey from plugin.

Parameters:
surveyId - Survey id
Returns:
The respondent object
Throws:
LockException - If the survey is locked
SurveySystemException - If an error occurs in the system.

createSurvey

public static Survey createSurvey(User user,
                                  long folderId)
                           throws SurveySecurityException,
                                  SurveySystemException
Creates a survey. Require permission to create surveys in the parent folder.
The survey will be empty, with just the survey id set. Survey attributes must then be set, and stored with the updateSurvey() method.
The creator will get full access to the newly created survey.

Parameters:
user - User
folderId - Id of the folder where the new survey will be placed (parent folder). Main folder has id -1.
Returns:
Survey
Throws:
SurveySecurityException - If the user is unauthorized to create surveys in this folder
SurveySystemException - If any error occurs in the system.

deleteFolder

public static void deleteFolder(User user,
                                long folderId)
                         throws java.lang.IllegalArgumentException,
                                SurveySecurityException,
                                SurveySystemException
Delete a folder by id. All surveys and sub-folders must be deleted before calling this method or IllegalArgumentException will be thrown. The root folder (folder id -1) cannot be deleted.

Parameters:
user - Current user
folderId - Id of folder to be deleted.
Throws:
SurveySecurityException - If the user is not authorized to delete the folder.
java.lang.IllegalArgumentException - If the folder contains surveys or sub-folders and can't be deleted.
SurveySystemException - If any error occurs in the system.

deleteIncompleteRespondents

public static void deleteIncompleteRespondents(User user,
                                               long surveyId)
                                        throws SurveySecurityException,
                                               SurveySystemException
Removes all incomplete respondents for the survey permanently. Require permission to administer respondents is the survey.

Parameters:
surveyId - Survey id
user - User
Throws:
SurveySecurityException - If the user is unauthorized to delete respondents in the survey
SurveySystemException - If any error occurs in the system.

deleteRespondent

public static void deleteRespondent(User user,
                                    long respondentId,
                                    long surveyId)
                             throws SurveySecurityException,
                                    SurveySystemException
Removes a respondent permanently. Require permission to administer respondents is the survey.

Parameters:
respondentId - Respondent id
user - User
surveyId - Survey id
Throws:
SurveySystemException - If any error occurs in the system.
SurveySecurityException - If the user is unauthorized to delete respondents in the survey

deleteRespondents

public static void deleteRespondents(User user,
                                     long surveyId)
                              throws SurveySecurityException,
                                     SurveySystemException
Removes all respondents for the survey permanently. Require permission to administer respondents is the survey.

Parameters:
user - User
surveyId - Survey id
Throws:
SurveySecurityException - If the user is unauthorized to delete respondents in the survey
SurveySystemException - If any error occurs in the system.

deleteSurvey

public static void deleteSurvey(User user,
                                long surveyId)
                         throws LockException,
                                SurveySecurityException,
                                RespondentsExistException,
                                SurveySystemException
Delete a survey by survey id. Respondents should be deleted before calling this method. Use deleteAllRespondents() method. Require permission to delete the survey.

Parameters:
user - Current user
surveyId - Id of survey to be deleted.
Throws:
RespondentsExistException - If respondents exist
SurveySecurityException - If the user is unauthorized to delete the survey.
LockException - If object is locked by another user
SurveySystemException - If an error occurs in the system.

storeRespondent

public static void storeRespondent(long respondentId,
                                   long surveyId)
                            throws SurveySystemException
Save respondent to the storage. This will store the entire respondent, with all responses.
ATTENTION: The responses should be validated before calling this method! (With calling Question.validate() method).

Parameters:
respondentId - Respondent id
surveyId - Survey id
Throws:
SurveySystemException - If any error occurs in the system.

updateSurvey

public static void updateSurvey(User user,
                                long surveyId)
                         throws SurveySystemException,
                                SurveySecurityException
Updates a survey in the storage.

Parameters:
user - Current user
surveyId - Id of the survey to update
Throws:
SurveySystemException - If any error occurs in the system.
SurveySecurityException - If the user is unauthorized to update the survey

Copyright © ObjectPlanet Inc. All Rights Reserved.

Built on May 7 2003