com.objectplanet.survey.plugin.api
Class Invitation

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

public class Invitation
extends java.lang.Object

Class represents a survey invitation.
Invitations are used to invite people to participate in a survey. There can be 0 to many invitations per survey, and 1 to many invitees in one invitation.
The invitation must be created before you can start adding invitees.

1. Create invitation:
   

                                                                 Invitation invitation     = new Invitation(String name, User user);
    

2. Set invitation attributes:
   

                                                                    invitation.setFromName("Your name");
                                                                    invitation.setFromEmail("yourEmail@smth.com");
                                                                    invitation.setInvitationDate(dateToSend);
                                                                    ...
    

3. Add invitation to the survey:

    survey.addInvitation(invitation);
    

4. Add invitees (see addInvitees())
5. Activate the invitation, so that emails are sent to the invitees when the invitation date comes:
   

    survey.startInvitation(invitation.getInvitationId());
    

None of the changes to invitation attributes are reflected in the system until survey.updateInvitation(invitation) is called.

Author:

Irina Brun

Created:

28. march 2003

Field Summary

static java.lang.String	ID_PLACE_HOLDER
static java.lang.String	KEY_PLACE_HOLDER
static java.lang.String	PANELIST_ID_PLACE_HOLDER
static java.lang.String	REOPEN_PLACE_HOLDER

Constructor Summary

Invitation(java.lang.String invitationName, com.objectplanet.survey.business.User user)
Constructor for the Invitation object

Method Summary

void	addInvitee(java.lang.String email, java.lang.String inviteeName, java.util.HashMap attributes) Adds new invitee to the invitation.
void	addInvitees(User user, java.io.File file, java.lang.String delimiter) Add invitees from the file.
long	addInviteesInThread(User user, java.io.File file, java.lang.String delimiter) Add invitees from the file.
void	deleteInvitees() Delete all invitees
void	deleteInvitees(long[] invitees) Delete invitees
java.lang.String	getContentType() Sets the content type for the message.
java.lang.String	getFromEmail() Gets the from email.
java.lang.String	getFromName() Gets the from name.
long	getInvitationDate() Gets the invitation date.
long	getInvitationId() Gets the invitation id
java.lang.String	getInvitationMessage() Gets the invitation message (in the email sent to invitee)
java.lang.String	getInvitationName() Gets the invitation name.
long	getInvitationSentDate() Get the date when invitation email was sent.
java.lang.String	getInvitationSubject() Gets the invitation subject (in the email sent to invitee)
Invitee	getInvitee(long inviteeId) Gets an invitee from storage
long	getInviteeCount() Get invitee count
long[]	getInviteeIds() Gets array of all invitee ids.
java.lang.String	getLastReminderMessage() Get message of the last reminder.
java.lang.String	getLastReminderSubject() Get subject of the last reminder.
long	getReminder1Date() Gets the date when the first reminder is scheduled to be sent.
long	getReminder1SentDate() Get the date when first reminder was sent.
long	getReminder2Date() Gets the date when the second reminder is scheduled to be sent.
long	getReminder2SentDate() Get the date when second reminder was sent.
long	getReminder3Date() Gets the date when the third reminder is scheduled to be sent.
long	getReminder3SentDate() Get the date when third reminder was sent.
long	getReminder4Date() Gets the date when the fourth reminder is scheduled to be sent.
long	getReminder4SentDate() Get the date when fourth reminder was sent.
long	getReminder5Date() Gets the date when the fifth reminder is scheduled to be sent.
long	getReminder5SentDate() Get the date when fifth reminder was sent.
int	getReminderCount() Gets the reminder count.
java.lang.String	getReminderMessage() Gets the reminder message.
java.lang.String	getReminderSubject() Gets the reminder subject.
long[]	getSendDates() Get array of dates when invitation will be sent.
long	getSurveyId() Get survey id the invitation belongs to
java.lang.String	getTaskStatus() Gets the invitation task status.
boolean	hasBusinessObject() Deprecated. The Invitation class has no longer reference to the business object. All data is cached in this class
void	keepBusinessObject() Deprecated. This method has no longer any effect on performance. The Invitation class has no longer reference to the business object. All data is cached in this class
void	releaseBusinessObject() Deprecated. the Invitation class has no longer reference to the business object. All data is cached in this class
void	setContentType(java.lang.String contentType) Sets the content type for the message.
void	setFromEmail(java.lang.String fromEmail) Sets the from email.
void	setFromName(java.lang.String fromName) Sets the from name.
void	setInvitationDate(long invitationDate) Sets the invitation date
void	setInvitationMessage(java.lang.String invitationMessage) Sets the invitation message (in the email sent to invitee)
void	setInvitationName(java.lang.String invitationName) Sets the invitation name (used in listing of invitations in the admin screens).
void	setInvitationSubject(java.lang.String invitationSubject) Sets the invitation subject (in the email sent to invitee)
void	setInviteeProperty(long inviteeId, java.lang.String attributeName, java.lang.String attributeValue) Set or Update an invitee attribute
void	setLastReminderMessage(java.lang.String lastReminderMessage) Set message of the last reminder.
void	setLastReminderSubject(java.lang.String lastReminderSubject) Set subject of the last reminder.
void	setReminder1Date(long reminder1Date) Sets the date when the first reminder will be sent.
void	setReminder2Date(long reminder2Date) Sets the date when the second reminder will be sent.
void	setReminder3Date(long reminder3Date) Sets the date when the third reminder will be sent.
void	setReminder4Date(long reminder4Date) Sets the date when the fourth reminder will be sent.
void	setReminder5Date(long reminder5Date) Sets the date when the fifth reminder will be sent.
void	setReminderMessage(java.lang.String reminderMessage) Sets the reminder message.
void	setReminderSubject(java.lang.String reminderSubject) Sets the reminder subject.
void	setSendDates(long[] dates) Set dates when invitation and reminders will be sent.
void	updateInvitee(long inviteeId, java.lang.String inviteeName, java.lang.String inviteeEmail) Update invitee

Methods inherited from class java.lang.Object

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

Field Detail

KEY_PLACE_HOLDER

public static final java.lang.String KEY_PLACE_HOLDER

See Also:

Constant Field Values

ID_PLACE_HOLDER

public static final java.lang.String ID_PLACE_HOLDER

See Also:

Constant Field Values

REOPEN_PLACE_HOLDER

public static final java.lang.String REOPEN_PLACE_HOLDER

See Also:

Constant Field Values

PANELIST_ID_PLACE_HOLDER

public static final java.lang.String PANELIST_ID_PLACE_HOLDER

See Also:

Constant Field Values

Constructor Detail

Invitation

public Invitation(java.lang.String invitationName,
                  com.objectplanet.survey.business.User user)

Constructor for the Invitation object

Parameters:

user - who create the invitation

Method Detail

setInvitationName

public void setInvitationName(java.lang.String invitationName)

Sets the invitation name (used in listing of invitations in the admin screens).

Parameters:

invitationName - The new invitation name

setFromName

public void setFromName(java.lang.String fromName)

Sets the from name. Used when sending emails. This is the from name in the email header

Parameters:

fromName - The new from name value

setFromEmail

public void setFromEmail(java.lang.String fromEmail)
                  throws java.lang.IllegalArgumentException

Sets the from email. This is the sender email address when invitations are sent.

Parameters:

fromEmail - The new from email value

Throws:

java.lang.IllegalArgumentException - If invalid email

setInvitationDate

public void setInvitationDate(long invitationDate)

Sets the invitation date

Parameters:

invitationDate - The new invitation date value

setContentType

public void setContentType(java.lang.String contentType)

Sets the content type for the message. Usually "text/plain" and "text/html".

Parameters:

contentType - The content type

setInvitationSubject

public void setInvitationSubject(java.lang.String invitationSubject)

Sets the invitation subject (in the email sent to invitee)

Parameters:

invitationSubject - The new invitation subject

setInvitationMessage

public void setInvitationMessage(java.lang.String invitationMessage)

Sets the invitation message (in the email sent to invitee)

Parameters:

invitationMessage - The new invitation message

setReminderSubject

public void setReminderSubject(java.lang.String reminderSubject)

Sets the reminder subject. This is the subject of the email sent to invitee if the survey is not responded to.

Parameters:

reminderSubject - The new reminder subject value

setReminderMessage

public void setReminderMessage(java.lang.String reminderMessage)

Sets the reminder message. This is the message of the email sent to invitee if the survey is not responded to.

Parameters:

reminderMessage - The new reminder message value

getInvitationId

public long getInvitationId()

Gets the invitation id

Returns:

The invitation id value

getInvitationName

public java.lang.String getInvitationName()

Gets the invitation name. (used in listing of invitations in the admin screens).

Returns:

The invitation name value

getFromName

public java.lang.String getFromName()

Gets the from name. Used when sending emails. This is the from name in the email header.

Returns:

The from name value

getFromEmail

public java.lang.String getFromEmail()

Gets the from email. This is the sender email address when invitations are sent.

Returns:

The from email value

getInvitationDate

public long getInvitationDate()

Gets the invitation date.

Returns:

The invitation date value

getReminderCount

public int getReminderCount()

Gets the reminder count. This is the number of times a reminder will be sent out if invitee has not responded to survey.

Returns:

The reminder count value

getContentType

public java.lang.String getContentType()

Sets the content type for the message.

Returns:

The content type

getInvitationSubject

public java.lang.String getInvitationSubject()

Gets the invitation subject (in the email sent to invitee)

Returns:

The invitation subject

getInvitationMessage

public java.lang.String getInvitationMessage()

Gets the invitation message (in the email sent to invitee)

Returns:

The invitation message

getReminderSubject

public java.lang.String getReminderSubject()

Gets the reminder subject. This is the subject of the email sent to invitee if the survey is not responded to.

Returns:

The reminder subject

getReminderMessage

public java.lang.String getReminderMessage()

Gets the reminder message. This is the message of the email sent to invitee if the survey is not responded to.

Returns:

The reminder message value

getLastReminderMessage

public java.lang.String getLastReminderMessage()

Get message of the last reminder.

Returns:

last reminder message

setLastReminderMessage

public void setLastReminderMessage(java.lang.String lastReminderMessage)

Set message of the last reminder.

getLastReminderSubject

public java.lang.String getLastReminderSubject()

Get subject of the last reminder.

Returns:

last reminder message

setLastReminderSubject

public void setLastReminderSubject(java.lang.String lastReminderSubject)

Set subject of the last reminder.

getSendDates

public long[] getSendDates()

Get array of dates when invitation will be sent. First date is invitation date, second date is first reminder date and so on.

setSendDates

public void setSendDates(long[] dates)

Set dates when invitation and reminders will be sent. First date is invitation date, second date is first reminder date and so on. Can be up to 5 reminders (so, dates array can have maximum length of 6).

getReminder1Date

public long getReminder1Date()

Gets the date when the first reminder is scheduled to be sent. The real date when reminder was sent can be retrieved with getReminder1SentDate() method.

Returns:

first reminder date

setReminder1Date

public void setReminder1Date(long reminder1Date)

Sets the date when the first reminder will be sent.

getReminder2Date

public long getReminder2Date()

Gets the date when the second reminder is scheduled to be sent. The real date when reminder was sent can be retrieved with getReminder2SentDate() method.

Returns:

first reminder date

setReminder2Date

public void setReminder2Date(long reminder2Date)

Sets the date when the second reminder will be sent.

getReminder3Date

public long getReminder3Date()

Gets the date when the third reminder is scheduled to be sent. The real date when reminder was sent can be retrieved with getReminder3SentDate() method.

Returns:

first reminder date

setReminder3Date

public void setReminder3Date(long reminder3Date)

Sets the date when the third reminder will be sent.

getReminder4Date

public long getReminder4Date()

Gets the date when the fourth reminder is scheduled to be sent. The real date when reminder was sent can be retrieved with getReminder4SentDate() method.

Returns:

first reminder date

setReminder4Date

public void setReminder4Date(long reminder4Date)

Sets the date when the fourth reminder will be sent.

getReminder5Date

public long getReminder5Date()

Gets the date when the fifth reminder is scheduled to be sent. The real date when reminder was sent can be retrieved with getReminder5SentDate() method.

Returns:

first reminder date

setReminder5Date

public void setReminder5Date(long reminder5Date)

Sets the date when the fifth reminder will be sent.

getSurveyId

public long getSurveyId()

Get survey id the invitation belongs to

Returns:

survey id

getInvitationSentDate

public long getInvitationSentDate()

Get the date when invitation email was sent. Returns 0 if invitation has not yet been sent.

Returns:

date when reminder was sent

getReminder1SentDate

public long getReminder1SentDate()

Get the date when first reminder was sent. Returns 0 if reminder has not yet been sent.

Returns:

date when reminder was sent

getReminder2SentDate

public long getReminder2SentDate()

Get the date when second reminder was sent. Returns 0 if reminder has not yet been sent.

Returns:

date when reminder was sent

getReminder3SentDate

public long getReminder3SentDate()

Get the date when third reminder was sent. Returns 0 if reminder has not yet been sent.

Returns:

date when reminder was sent

getReminder4SentDate

public long getReminder4SentDate()

Get the date when fourth reminder was sent. Returns 0 if reminder has not yet been sent.

Returns:

date when reminder was sent

getReminder5SentDate

public long getReminder5SentDate()

Get the date when fifth reminder was sent. Returns 0 if reminder has not yet been sent.

Returns:

date when reminder was sent

addInvitees

public void addInvitees(User user,
                        java.io.File file,
                        java.lang.String delimiter)
                 throws LockException,
                        SurveySystemException,
                        com.objectplanet.survey.business.invitation.InvalidContentException

Add invitees from the file. See Invitee data format in the Opinio documentation for file data format. First the file is validated for valid content. Then a temp copy of the file created with the same name as the original file. Temp file is located in the opinio temp folder. Temp file is deleted when import is complete. IMPORTANT: invitee import is implemented without thread. So the method will return only when all invitees in the file are imported. Use this method only when number of invitees is low!

Parameters:

user - user who adds invitees

file - file with invitees data to import. One per line.

delimiter - Delimiter between invitee data parts

Throws:

InvalidContentException - Thrown if content of the file is invalid

LockException

SurveySystemException

com.objectplanet.survey.business.invitation.InvalidContentException

addInviteesInThread

public long addInviteesInThread(User user,
                                java.io.File file,
                                java.lang.String delimiter)
                         throws LockException,
                                SurveySystemException,
                                com.objectplanet.survey.business.invitation.InvalidContentException

Add invitees from the file. See Invitee data format in the Opinio documentation for file data format. First the file is validated for valid content. Then a temp copy of the file created with the same name as the original file. Temp file is located in the opinio temp folder. Temp file is deleted when import is complete. IMPORTANT: invitee import is implemented in a thread. So the method will return once the thread is started. If you want to know when the import is complete, listen for com.objectplanet.survey.event.events.InviteeImportEvent with status InviteeImportEvent.STATUS_COMPLETED

Parameters:

user - user who adds invitees

file - file with invitees data to import. One per line.

delimiter - Delimiter between invitee data parts

Returns:

unique import id. This id can be used for thread identification in InviteeImportEvent

Throws:

InvalidContentException - Thrown if content of the file is invalid

LockException

SurveySystemException

com.objectplanet.survey.business.invitation.InvalidContentException

addInvitee

public void addInvitee(java.lang.String email,
                       java.lang.String inviteeName,
                       java.util.HashMap attributes)
                throws LockException,
                       SurveySystemException

Adds new invitee to the invitation.

Parameters:

email - Valid email address

inviteeName - Invitee name

attributes - HashMap of invitee attributes. Pass any attributes you want to be associated with the invitee and his responses (String keys and String values)

Throws:

LockException - Thrown if the survey is locked by another user.

java.lang.IllegalArgumentException - Thrown if email address is invalid

SurveySystemException - Thrown if an error occurs in the system.

deleteInvitees

public void deleteInvitees()
                    throws LockException,
                           SurveySystemException

Delete all invitees

Throws:

LockException - Thrown if the survey is locked by another user.

SurveySystemException - Thrown if an error occurs in the system.

deleteInvitees

public void deleteInvitees(long[] invitees)
                    throws LockException,
                           SurveySystemException

Delete invitees

Parameters:

invitees - List of invitee ids to be deleted.

Throws:

LockException - Thrown if the survey is locked by another user.

SurveySystemException - Thrown if an error occurs in the system.

updateInvitee

public void updateInvitee(long inviteeId,
                          java.lang.String inviteeName,
                          java.lang.String inviteeEmail)
                   throws LockException,
                          SurveySystemException,
                          java.lang.IllegalArgumentException

Update invitee

Parameters:

inviteeId - Invitee id

inviteeName - New invitee name

inviteeEmail - New invitee email

Throws:

LockException - Thrown if the survey is locked by another user.

SurveySystemException - Thrown if an error occurs in the system.

java.lang.IllegalArgumentException - If invitee email is invalid

setInviteeProperty

public void setInviteeProperty(long inviteeId,
                               java.lang.String attributeName,
                               java.lang.String attributeValue)
                        throws LockException,
                               SurveySystemException

Set or Update an invitee attribute

Parameters:

inviteeId - Invitee id

attributeName - Name of the property to set/change

attributeValue - The value of the property

Throws:

LockException - Thrown if the survey is locked by another user.

SurveySystemException - Thrown if an error occurs in the system.

getInvitee

public Invitee getInvitee(long inviteeId)
                   throws SurveySystemException

Gets an invitee from storage

Parameters:

inviteeId - Id of invitee to retrieve

Returns:

The invitee value

Throws:

SurveySystemException - Thrown if an error occurs in the system.

getInviteeIds

public long[] getInviteeIds()
                     throws SurveySystemException

Gets array of all invitee ids.

Returns:

The invitee ids

Throws:

SurveySystemException - Thrown if an error occurs in the system.

getInviteeCount

public long getInviteeCount()
                     throws SurveySystemException

Get invitee count

Returns:

Invitee count

Throws:

SurveySystemException - Thrown if an error occurs in the system.

getTaskStatus

public java.lang.String getTaskStatus()
                               throws SurveySecurityException,
                                      SurveySystemException

Gets the invitation task status.

Returns:

Status.

Throws:

SurveySystemException - If an error occurs in the system.

SurveySecurityException

keepBusinessObject

public void keepBusinessObject()
                        throws SurveySystemException

Deprecated. This method has no longer any effect on performance. The Invitation class has no longer reference to the business object. All data is cached in this class

Get and keep the business object. See ATTENTION .

Throws:

SurveySystemException - If an error occurs in the system.

releaseBusinessObject

public void releaseBusinessObject()

Deprecated. the Invitation class has no longer reference to the business object. All data is cached in this class

Release the business object. See ATTENTION

hasBusinessObject

public boolean hasBusinessObject()

Deprecated. The Invitation class has no longer reference to the business object. All data is cached in this class

Check if this invitation has reference to the business Invitation object. See ATTENTION .

Returns:

Always return false