AuthFactory.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 java.util.concurrent.ExecutorService;
import javax.sql.DataSource;

import net.metanotion.authident.AuthPassword;
import net.metanotion.authident.CredentialedUserToken;
import net.metanotion.email.MailerProxy;
import net.metanotion.email.MailMerge;
import net.metanotion.io.ClassLoaderFileSystem;
import net.metanotion.io.File;
import net.metanotion.io.FileSystem;
import net.metanotion.util.Dispatcher;
import net.metanotion.util.SecureString;
import net.metanotion.web.RequestObject;
import net.metanotion.web.concrete.WebInterfaceDispatcher;

/** This is the main entry point into the forms auth package for an application. */
public final class AuthFactory {
	private static final WebInterfaceDispatcher<? extends Object> dispatcher;

	/** This is an implementation of the Validate interface that ALWAYS validate's a username. */
	public static final Validate ALWAYS_VALIDATE = new Validate() {
		@Override public void validate(final String username, final SecureString password, final RequestObject ro) { }
	};

	/** This is an implementation of the CreateAccount interface that does nothing. */
	public static final CreateAccount NULL_CREATE_ACCOUNT = new CreateAccount() {
		@Override public void account(final String username, final CredentialedUserToken ut, final RequestObject ro) { }
	};

	/** This is the file system containing the default email templates that can be used for
	{@link net.metanotion.email.MailMerge} based implementations of
	{@link net.metanotion.formsauth.AuthMailer}.
	*/
	public static final FileSystem<File> DEFAULT_EMAIL_TEMPLATES =
		new ClassLoaderFileSystem(AuthFactory.class.getClassLoader(), "/net/metanotion/formsauth/htmltemplates/emails");

	/** A "default" logging/null implementation of AuthMailer. This implementation does "nothing" when an email is sent
	except log the request to a class logger for debuggin purposes. */
	public static final AuthMailer LOGGING_AUTH_MAILER = MailerProxy.mailLogger(AuthMailer.class);

	/** Generate an implementation of AuthMailer that uses the MailMerge class to generate emails.
		@param es An executor service to submit messages to for queueing.
		@param mm An instance of the MailMerge class to create the actual messages to send.
		@param senderEmail The email address of the message sender. (e.g. noreply@example.com)
		@param urls The base URL constants to merge with every class.
		@return An implementation of AuthMailer that queues messages generated from templates.
	*/
	public static AuthMailer mailMerge(final ExecutorService es,
			final MailMerge mm,
			final String senderEmail,
			final AuthMailer.Urls urls) {
		return MailerProxy.generate(AuthMailer.class, es, mm, senderEmail, urls);
	}

	static {
		try {
			dispatcher = new WebInterfaceDispatcher<AuthAPI>(AuthAPI.class);
		} catch (java.io.IOException ioe) {
			throw new RuntimeException(ioe);
		}
	}

	/** Return a suitable dispatcher for handling {@link net.metanotion.formsauth.AuthAPI} HTTP Requests. This
		method is static because it requires no information/configuration.
		@return A dispatcher suitable for any web application.
	*/
	public static Dispatcher<? extends Object,RequestObject> dispatcher() { return dispatcher; }

	/** Create a new instance of the {@link net.metanotion.formsauth.AuthAPI} service that accepts any new account.
		This is the service your session will expose via Unknown.
		@param ds A data source for the SQL database that provides persistance for the extended information about accounts(see
			src/main/sql/auth.schema.sql for the DDL).
		@param pw An instance of a password authentication service from the net.metanotion.authident package. This is used to
			authenticate the username/password pairs from the user and create acconts.
		@param mailer An instance of mailing service to send transactional emails related to account actions(e.g. account
			validation, password resets, and so on). A null implementation that simply logs API calls is provided by
			LOGGING_AUTH_MAILER.
		@param prefix The string value to prefix all URI's associated with an instance of this service.
		@return An instance of the WebAuthExtras service.
	*/
	public static AuthAPI instance(final DataSource ds, final AuthPassword pw, final AuthMailer mailer, final String prefix) {
		return AuthFactory.instance(ds, pw, mailer, prefix, ALWAYS_VALIDATE, NULL_CREATE_ACCOUNT);
	}

	/** Create a new instance of the WebAuthExtras service with the package defaults.
		This is the service your session will expose via Unknown.
		@param ds A data source for the SQL database that provides persistance for the extended information about accounts(see
			src/main/sql/auth.schema.sql for the DDL).
		@param pw An instance of a password authentication service from the net.metanotion.authident package. This is used to
			authenticate the username/password pairs from the user and create acconts.
		@param mailer An instance of mailing service to send transactional emails related to account actions(e.g. account
			validation, password resets, and so on). A null implementation that simply logs API calls is provided by
			LOGGING_AUTH_MAILER.
		@param prefix The string value to prefix all URI's associated with an instance of this service.
		@param v A new account information validator. This instance is used to determine if a new account is acceptable.
		@param ca An event listener for newly created accounts. This object will receive information about all
			successfully created acconts.
		@return An instance of the AuthAPI service
	*/
	public static AuthAPI instance(final DataSource ds,
			final AuthPassword pw,
			final AuthMailer mailer,
			final String prefix,
			final Validate v,
			final CreateAccount ca) {
		final AuthStore store = new AuthStoreJDBC(ds);
		return new AuthImpl(store, pw, mailer, prefix, v, ca);
	}

	/** Create an in memory test-instance of the FormsAuthAPI.
		@param pw An instance of a password authentication service from the net.metanotion.authident package. This is
			used to authenticate the username/password pairs from the user and create acconts.
		@param prefix The string value to prefix all URI's associated with an instance of this service.
		@return An instance of the AuthAPI service
	*/
	public static AuthAPI instance(final AuthPassword pw,
			final String prefix) {
		final AuthStore store = new AuthStoreSimple();
		return new AuthImpl(store, pw, LOGGING_AUTH_MAILER, prefix, ALWAYS_VALIDATE, NULL_CREATE_ACCOUNT);
	}
}