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 surveys, survey folders, and survey respondents.

Author:

Irina Brun, Torgeir Lund

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	deleteRespondentFromCache(User user, long surveyId, long respondentId) Removes a respondent from cache.
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 void	exportCSV(CSVExportParameters parameters) Exports survey data to a CSV file.
static Folder	getFolder(User user, long folderId) Get a folder by id.
static Respondent	getNotCachedRespondent(long respondentId, long surveyId) Get a respondent without adding it to the cache
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 Survey	getSurvey(User user, long surveyId, java.lang.String languageCode) Get a survey, by survey id and language code.
static Survey	getSurvey(User user, java.lang.String surveyId) Gets a survey by custom survey id.
static java.lang.String	getSurveyPreviewKey(long surveyId) Get preview key for the survey
static long	getSurveysCreatedCount(long userId, long fromDate) Gets the number of surveys created by a user from a specified fromDate to now
static long	getSurveysCreatedCount(long userId, long fromDate, long toDate) Gets the number of surveys created by a user from a specified fromDate to a specified toDate
static void	releaseLock(long surveyId) Releases a lock on a survey.
static void	removeSurveyFromCache(long surveyId) This method will remove the survey from cache if survey has been loaded and cached in the system.
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.

getNotCachedRespondent

public static Respondent getNotCachedRespondent(long respondentId,
                                                long surveyId)
                                         throws SurveySystemException

Get a respondent without adding it to the cache

Parameters:

data.getSurveyProxy() - Survey proxy associated with respondent

respondentId - Respondent id

Returns:

The respondent object

Throws:

SurveySystemException - Survey System Exception

getSurveyPreviewKey

public static java.lang.String getSurveyPreviewKey(long surveyId)
                                            throws SurveySystemException

Get preview key for the survey

Parameters:

surveyId -

Returns:

key for survey preview

Throws:

SurveySystemException - If an error occurs in the system.

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 uncompleted 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.

getSurvey

public static Survey getSurvey(User user,
                               java.lang.String surveyId)
                        throws SurveySecurityException,
                               SurveySystemException

Gets a survey by custom survey id.

Parameters:

user - User

surveyId - The custom survey id

Returns:

The survey object. Null if not found.

Throws:

SurveySecurityException - Thrown if the user doesn't have read access to the survey.

SurveySystemException - If error occurs.

getSurvey

public static Survey getSurvey(User user,
                               long surveyId,
                               java.lang.String languageCode)
                        throws SurveySecurityException,
                               SurveySystemException

Get a survey, by survey id and language code. If the specified language code is not the default language a child survey with the language code will be returned. If no survey exists with the specified language code the method will return null.

Parameters:

user - User

surveyId - Id of survey to get

surveyId - The language code

Returns:

The survey.

Throws:

com.objectplanet.survey.persistence.PersistenceException - Persistence exception

SurveySecurityException - If unauthorized

SurveySystemException

getSurveysCreatedCount

public static long getSurveysCreatedCount(long userId,
                                          long fromDate,
                                          long toDate)
                                   throws SurveySystemException

Gets the number of surveys created by a user from a specified fromDate to a specified toDate

Parameters:

userId - The user id

fromDate - The specified fromDate

toDate - The specified toDate

Returns:

The number of surveys

Throws:

SurveySystemException - If any error occurs in the system.

getSurveysCreatedCount

public static long getSurveysCreatedCount(long userId,
                                          long fromDate)
                                   throws SurveySystemException

Gets the number of surveys created by a user from a specified fromDate to now

Parameters:

userId - The user id

fromDate - The specified fromDate

Returns:

The number of surveys

Throws:

SurveySystemException - If any 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

deleteRespondentFromCache

public static void deleteRespondentFromCache(User user,
                                             long surveyId,
                                             long respondentId)
                                      throws SurveySystemException

Removes a respondent from cache. If respondent is not stored, some data could be lost. To make sure this does not occur, make sure respondents are stored/updated between each survey page (this is set in the survey attributes screen, or by calling the survey api methods), or call storeRespondent() before calling deleteRespondentFromCache(). This could potentially slow things down, because it will save all answers to all questions each time the method is called.

This method will not work across the cluster (applicable only if clustering enable). The method will only remove the respondent from the local cache.

Parameters:

respondentId - id of respondent to be removed

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 cache

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.

removeSurveyFromCache

public static void removeSurveyFromCache(long surveyId)

This method will remove the survey from cache if survey has been loaded and cached in the system. Calling this method will force the system to upload the entire survey from the database next time the survey is accessed.

Parameters:

surveyId -

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

releaseLock

public static void releaseLock(long surveyId)
                        throws SurveySystemException

Releases a lock on a survey.

Parameters:

surveyId - Id of the survey to release the lock on.

Throws:

SurveySystemException - If any error occurs in the system.

exportCSV

public static void exportCSV(CSVExportParameters parameters)
                      throws SurveySystemException

Exports survey data to a CSV file. Standard raw data export settings are used, in addition to some parameters specified. The export will be put in a worker-queue. No more than 5 (configurable) concurrent exports or report generation jobs will be executed at any given time. If there are currently running 5 jobs, this export will wait until there are available slots. This feature is only available in the Corporate or Enterprise edition.

Parameters:

parameters - The additional settings used for the report. See

Throws:

SurveySystemException

See Also:

for details of available parameters.