com.objectplanet.survey.plugin.api
Class Invitation

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

public class Invitation
extends java.lang.Object

ATTENTION: This class is a facade for the system business Invitation. 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.

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.

  1. Create invitation:
     Invitation invitation = survey.addInvitation("Invitation");
  2. Set invitation attributes:
     invitation.setFromName("You name");
     invitation.setFromEmail("youEmail@smth.com");
     ...
  3. Update invitation attributes:
     survey.updateInvitation(invitation.getInvitationId());
  4. Add invitees
  5. Start invitation:
     survey.startInvitation(invitation.getInvitationId());

If the invitaiton is running, calling a set-method will stop the invitation. To start the invitation after updating, call survey.startInvitation().

Author:
Irina Brun
Created:
28. march 2003

Method Summary
 java.lang.String[] addInvitees(java.lang.String invitees)
          Adds invitees to the invitation.
 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.
 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.
 int getReminderCount()
          Gets the reminder count.
 long getReminderInterval()
          Gets the reminder interval.
 java.lang.String getReminderMessage()
          Gets the reminder message.
 java.lang.String getReminderSubject()
          Gets the reminder subject.
 java.lang.String getTaskStatus()
          Gets the invitation task status.
 boolean hasBusinessObject()
          Check if this invitation has reference to the business Invitation object.
 void keepBusinessObject()
          Get and keep the business object.
 void releaseBusinessObject()
          Release the business object.
 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 setReminderCount(int reminderCount)
          Sets the reminder count.
 void setReminderInterval(long reminderInterval)
          Sets the reminder interval (number of days between each reminder if invitee has not responded to the survey).
 void setReminderMessage(java.lang.String reminderMessage)
          Sets the reminder message.
 void setReminderSubject(java.lang.String reminderSubject)
          Sets the reminder subject.
 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
 

Method Detail

setInvitationName

public void setInvitationName(java.lang.String invitationName)
                       throws LockException,
                              SurveySystemException
Sets the invitation name (used in listing of invitations in the admin screens).

Parameters:
invitationName - The new invitation name
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setFromName

public void setFromName(java.lang.String fromName)
                 throws LockException,
                        SurveySystemException
Sets the from name. Used when sending emails. This is the from name in the email header

Parameters:
fromName - The new from name value
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setFromEmail

public void setFromEmail(java.lang.String fromEmail)
                  throws LockException,
                         SurveySystemException,
                         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:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.
java.lang.IllegalArgumentException - If invalid email

setInvitationDate

public void setInvitationDate(long invitationDate)
                       throws LockException,
                              SurveySystemException
Sets the invitation date

Parameters:
invitationDate - The new invitation date value
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setReminderInterval

public void setReminderInterval(long reminderInterval)
                         throws LockException,
                                SurveySystemException
Sets the reminder interval (number of days between each reminder if invitee has not responded to the survey).

Parameters:
reminderInterval - The new reminder interval value
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setReminderCount

public void setReminderCount(int reminderCount)
                      throws LockException,
                             SurveySystemException
Sets the reminder count. This is the number of times a reminder will be sent out if invitee has not responded to survey.

Parameters:
reminderCount - The new reminder count value
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setContentType

public void setContentType(java.lang.String contentType)
                    throws LockException,
                           SurveySystemException
Sets the content type for the message. Usually "text/plain" and "text/html".

Parameters:
contentType - The content type
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setInvitationSubject

public void setInvitationSubject(java.lang.String invitationSubject)
                          throws LockException,
                                 SurveySystemException
Sets the invitation subject (in the email sent to invitee)

Parameters:
invitationSubject - The new invitation subject
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setInvitationMessage

public void setInvitationMessage(java.lang.String invitationMessage)
                          throws LockException,
                                 SurveySystemException
Sets the invitation message (in the email sent to invitee)

Parameters:
invitationMessage - The new invitation message
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setReminderSubject

public void setReminderSubject(java.lang.String reminderSubject)
                        throws LockException,
                               SurveySystemException
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
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

setReminderMessage

public void setReminderMessage(java.lang.String reminderMessage)
                        throws LockException,
                               SurveySystemException
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
Throws:
LockException - Thrown if the survey is locked by another user.
SurveySystemException - Thrown if an error occurs in the system.

getInvitationId

public long getInvitationId()
                     throws SurveySystemException
Gets the invitation id

Returns:
The invitation id value
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getInvitationName

public java.lang.String getInvitationName()
                                   throws SurveySystemException
Gets the invitation name. (used in listing of invitations in the admin screens).

Returns:
The invitation name value
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getFromName

public java.lang.String getFromName()
                             throws SurveySystemException
Gets the from name. Used when sending emails. This is the from name in the email header.

Returns:
The from name value
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getFromEmail

public java.lang.String getFromEmail()
                              throws SurveySystemException
Gets the from email. This is the sender email address when invitations are sent.

Returns:
The from email value
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getInvitationDate

public long getInvitationDate()
                       throws SurveySystemException
Gets the invitation date.

Returns:
The invitation date value
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getReminderInterval

public long getReminderInterval()
                         throws SurveySystemException
Gets the reminder interval. (number of days between each reminder if invitee has not responded to the survey)

Returns:
The reminderInterval value
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getReminderCount

public int getReminderCount()
                     throws SurveySystemException
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
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getContentType

public java.lang.String getContentType()
                                throws SurveySystemException
Sets the content type for the message.

Returns:
The content type
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getInvitationSubject

public java.lang.String getInvitationSubject()
                                      throws SurveySystemException
Gets the invitation subject (in the email sent to invitee)

Returns:
The invitation subject
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getInvitationMessage

public java.lang.String getInvitationMessage()
                                      throws SurveySystemException
Gets the invitation message (in the email sent to invitee)

Returns:
The invitation message
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getReminderSubject

public java.lang.String getReminderSubject()
                                    throws SurveySystemException
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
Throws:
SurveySystemException - Thrown if an error occurs in the system.

getReminderMessage

public java.lang.String getReminderMessage()
                                    throws SurveySystemException
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
Throws:
SurveySystemException - Thrown if an error occurs in the system.

addInvitees

public java.lang.String[] addInvitees(java.lang.String invitees)
                               throws LockException,
                                      SurveySystemException
Adds invitees to the invitation. The invitation must have been added to the survey before this method is called.
Invitees should be seperated with new line. Use space to separate email and name.
Invalid emails will not be added to the invitation. Example:
  StringBuffer invitees = new StringBuffer();
  invitees.append("smith@smth.com").append("\n");
  invitees.append("brown@smth.com Michael Brown").append("\n");
  invitees.append("olsen@smth");
 
Two invitees will be created:
  1. Email: smith@smth.com
    Name:
  2. Email: brown@smth.com
    Name: Michael Brown
The third email is invalid and will be returned.

Parameters:
invitees - List of invitees, one per line.
Returns:
Array of invalid emails. These were not added to the invitations. If null - no invalid email addresses were found.
Throws:
LockException - Thrown if the survey is locked by another user.
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

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
Get and keep the business object. See ATTENTION .

Throws:
SurveySystemException - If an error occurs in the system.

releaseBusinessObject

public void releaseBusinessObject()
Release the business object. See ATTENTION .


hasBusinessObject

public boolean hasBusinessObject()
Check if this invitation has reference to the business Invitation object. See ATTENTION .

Returns:
True/false

Copyright © ObjectPlanet Inc. All Rights Reserved.

Built on May 7 2003