package com.oreilly.jent.annotation.people;

/**
 * In general, you may use the code in this book in your programs and 
 * documentation. You do not need to contact us for permission unless 
 * you're reproducing a significant portion of the code. For example, 
 * writing a program that uses several chunks of code from this book does 
 * not require permission. Selling or distributing a CD-ROM of examples 
 * from O'Reilly books does require permission. Answering a question by 
 * citing this book and quoting example code does not require permission. 
 * Incorporating a significant amount of example code from this book into 
 * your product's documentation does require permission.
 * 
 * We appreciate, but do not require, attribution. An attribution usually 
 * includes the title, author, publisher, and ISBN. For example: 
 * 
 *   "Java Enterprise in a Nutshell, Third Edition, 
 *    by Jim Farley and William Crawford 
 *    with Prakash Malani, John G. Norman, and Justin Gehtland. 
 *    Copyright 2006 O'Reilly Media, Inc., 0-596-10142-2."
 *  
 *  If you feel your use of code examples falls outside fair use or the 
 *  permission given above, feel free to contact us at 
 *  permissions@oreilly.com.
 */

import java.util.Collection;
import java.util.Map;
import java.util.logging.Logger;

import com.oreilly.jent.annotation.people.util.ConfigSet;

/**
 * Interface to a data access object for Person objects.  This provides a 
 * facade that hides the particulars of the persistence scheme from the rest of
 * the application, allowing us to swap in/out different implementations
 * if the persistence changes.
 * 
 * @author <a href="mailto:jim@jimfarley.org">Jim Farley</a>
 *
 */
public abstract class PersonDAO {
    static public Logger sLog = Logger.getLogger(PersonDAO.class.getName());
    static private PersonDAO sDAO = null;
    // Default config file location
    static private final String sDefaultConfig = "/persondao.xml";
    
    // Standard search parameter names supported by DAO implementations
    static public final String FIRST_NAME = "firstName";
    static public final String LAST_NAME = "lastName";
    static public final String EMAIL = "email";
    
    // Static initializer of PersonDAO singleton.  Reads configuration
    // parameters from an XML file loaded from the classpath using the 
    // reference passed as an argument.
    //
    // The classpath reference must point to an XML file with the format:
    //
    //     <dao>
    //         <classname>org.jsmith.MyPersonDAOImpl</classname>
    //         <parameters>
    //           <my-param-1>foo</my-param-1>
    //           <my-param-2>bar</my-param-2>
    //         </parameters>
    //     </dao>
    //
    // The classname in the config file will be used to initialize a DAO 
    // implementation (using reflection to invoke the no-argument constructor
    // on the named class).  Then the entire config set will be passed to the 
    // DAO's init() method as a ConfigSet instance, so it can parse any
    // implementation-specific parameters from the rest of the file.
    
    static public void initSingleton(String configRef) {
        try {
            sLog.info("Initializing from " + configRef);
            ConfigSet config = new ConfigSet(configRef);
            String daoClass = config.getParameter("dao.classname");
            sDAO = (PersonDAO)Class.forName(daoClass).newInstance();
            sDAO.init(config);
        }
        catch (IllegalArgumentException iae1) {
            sLog.severe("Failed to initialize ConfigReader: " + 
                        iae1.getMessage());
        }
        catch (InstantiationException ie) {
            sLog.severe("Failed to initialize PersonDAO singleton: " + 
                        ie.getMessage());
        }
        catch (IllegalAccessException iae2) {
            sLog.severe("Failed to initialize PersonDAO singleton: " + 
                        iae2.getMessage());
        }
        catch (ClassNotFoundException cnfe) {
            sLog.severe("Failed to initialize PersonDAO singleton: " + 
                        cnfe.getMessage());
        }
    }
    
    /** Accessor for the PersonDAO singleton */
    static public PersonDAO getInstance() {
        if (sDAO == null) {
            initSingleton(sDefaultConfig);
        }
        return sDAO;
    }
    
    /** 
     *  Search method.  Search parameters are given as name/value pairs
     *  in the Map argument.  Known subclasses currently support the 
     *  following search parameter names:
     *  
     *      "firstName": Pattern matched against first names.
     *      "lastName" : Pattern matched against last names.
     *      "email"    : Pattern matches against email addresses.
     * 
     *  The known implementations also all support the "*" wildcard,
     *  converting it to the appropriate search syntax for their underlying
     *  persistence scheme.
     * 
     *  If no search parameters are given, or if unsuported search parameters
     *  are given, the DAO implementation should throw an InvalidSearchException.
     */
    abstract public Collection findPeople(Map searchParams)
        throws InvalidSearchException, PersistenceException;
    
    /** Find a person, given their unique identifier. */
    abstract public Person findPerson(String id)
        throws InvalidSearchException, PersistenceException;
    
    /** 
     *  Match a person to a given login account.  If no match possible, throw
     *  an InvalidSearchException.
     */
    abstract public Person findPersonByAcct(String acctID)
        throws InvalidSearchException, PersistenceException;
    
    /** 
     *  Initialize the DAO from the data provided in the config file.  Sub-classes
     *  implement this method to look for implementation-specific config
     *  parameters. 
     */
    abstract public void init(ConfigSet config);
}