AuthMailer.java

/***************************************************************************
   Copyright 2012 Emily Estes

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
***************************************************************************/
package net.metanotion.formsauth;


import javax.inject.Named;
import net.metanotion.email.MailerProxy;

/** This interface abstracts the Auth library's account management emails. Instead of
of sending the email directly, when the auth library wants to send a notification, it calls one
of methds in this interface with the information required to build the message. While there is
an implementation included that uses net.metanotion.email.MailMerge and a database table to store
queued messages, this is only one of many options. (Also, thereis a debugging implmentation that
merely logs notifications to the server logs.). */
@Named public interface AuthMailer {
	public static final String EMAIL = "email";
	public static final String VALIDATION_ID = "validationId";
	public static final String RESET_ID = "resetId";
	public static final String TOKEN = "token";

	/** This is the constants class for the variables to be merged with every message. */
	public static final class Urls implements MailerProxy.Constants<AuthMailer> {
		public final String validateUrl;
		public final String resetUrl;

		/** Create a new instance of the constants class.
			@param validateUrl The base URL to use for links involving validating an account.
			@param resetUrl The base URL to use for links involving reseting an account.
		*/
		public Urls(final String validateUrl, final String resetUrl) {
			this.validateUrl = validateUrl;
			this.resetUrl = resetUrl;
		}
	}

	/** This is the email sent when an account is first created.
		@param email The username/email address of the user who created the account.
		@param validationId the validation ID to be posted to %AUTH_PREFIX%/validateAccount in the form-encoded variable "vid"
		@param token The validation token to be posted to %AUTH_PREFIX%/validateAccount in the form-encoded variable "token"
	*/
	public void createAccount(@Named(EMAIL) String email,
		@Named(VALIDATION_ID) String validationId,
		@Named(TOKEN) String token);

	/** This is the email sent when a user adds an email address to a pre-existing account.
		@param email The username/email address of the user who created the account.
		@param validationId the validation ID to be posted to %AUTH_PREFIX%/validateAccount in the form-encoded variable "vid"
		@param token The validation token to be posted to %AUTH_PREFIX%/validateAccount in the form-encoded variable "token"
	*/
	public void addAccount(@Named(EMAIL) String email,
		@Named(VALIDATION_ID) String validationId,
		@Named(TOKEN) String token);

	/** This is the email sent when a user needs to revalidate their email address or re-request the validation token be resent
		because it has expired or been caught in a spam filter, etc.
		@param email The username/email address of the user who created the account.
		@param validationId the validation ID to be posted to %AUTH_PREFIX%/validateAccount in the form-encoded variable "vid"
		@param token The validation token to be posted to %AUTH_PREFIX%/validateAccount in the form-encoded variable "token"
	*/
	public void validationEmail(@Named(EMAIL) String email,
		@Named(VALIDATION_ID) String validationId,
		@Named(TOKEN) String token);

	/** This is the email sent when a user needs to reset the password on their account.
		In addition to the two variables here posted to %AUTH_PREFIX%/resetPassword "password" and "password2" are also to
		be sent when designing the form to submit this information.
		@param email The username/email address of the user who created the account.
		@param resetId the reset ID to be posted to %AUTH_PREFIX%/resetPassword in the form-encoded variable "rid"
		@param token The validation token to be posted to %AUTH_PREFIX%/resetPassword in the form-encoded variable "token"
	*/
	public void resetPassword(@Named(EMAIL) String email,
		@Named(RESET_ID) String resetId,
		@Named(TOKEN) String token);

	/** This is the email sent when a user when their account has been created by another system to send out a welcome
		email and the code to setup a password. This email also serves to validate the account. In addition to the two
		variables here posted to %AUTH_PREFIX%/resetPassword "password" and "password2" are also to be sent when
		designing the form to submit this information.
		@param email The username/email address of the user who created the account.
		@param resetId the reset ID to be posted to %AUTH_PREFIX%/resetPassword in the form-encoded variable "rid"
		@param token The validation token to be posted to %AUTH_PREFIX%/resetPassword in the form-encoded variable "token"
	*/
	public void welcomeWithPasswordReset(@Named(EMAIL) String email,
		@Named(RESET_ID) String resetId,
		@Named(TOKEN) String token);
}