/* ======================================================================
The Bodington System Software License, Version 1.0
  
Copyright (c) 2001 The University of Leeds.  All rights reserved.
  
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

1.  Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.

2.  Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

3.  The end-user documentation included with the redistribution, if any,
must include the following acknowledgement:  "This product includes
software developed by the University of Leeds
(http://www.bodington.org/)."  Alternately, this acknowledgement may
appear in the software itself, if and wherever such third-party
acknowledgements normally appear.

4.  The names "Bodington", "Nathan Bodington", "Bodington System",
"Bodington Open Source Project", and "The University of Leeds" must not be
used to endorse or promote products derived from this software without
prior written permission. For written permission, please contact
d.gardner@leeds.ac.uk.

5.  The name "Bodington" may not appear in the name of products derived
from this software without prior written permission of the University of
Leeds.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO,  TITLE,  THE IMPLIED WARRANTIES 
OF QUALITY  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO 
EVENT SHALL THE UNIVERSITY OF LEEDS OR ITS CONTRIBUTORS BE LIABLE FOR 
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE 
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.
=========================================================

This software was originally created by the University of Leeds and may contain voluntary 
contributions from others.  For more information on the Bodington Open Source Project, please 
see http://bodington.org/

====================================================================== */

package org.bodington.database;

/**
 * Class that allows lookups to be cached on something other than the primary
 * key of an object. All implementation of this class should have their own 
 * implementation of equals and hashCode.
 * 
 * You may wish to use an IndexKey if you have a lookup that is performed 
 * frequently against the database and would like to cache the results so 
 * repeated lookups don't hit the database. The index can be on more than one
 * column but the set of values must be unique.
 * 
 * As an example of how this might work I'll take the example of looking up
 * a PassPhrase object based on the username.
 * 
 * Firstly you should create a unique index on the table in the database so that
 * the database can never contain data that would break IndexKey lookups. 
 * Eg: CREATE UNIQUE INDEX uq_user_name ON pass_phrase(user_name)
 * 
 * Then create a class that implements the IndexKey interface that can be
 * used to store the information about the values in the index. In this example
 * the IndexKey implementation would just need to store the username. This
 * class must also override the equals and hashCode methods so that the checks
 * are based on the data in the object rather than the object itself. The class
 * should also implement the whereClause() and cacheNull() methods.
 * 
 * The class that is going to be retieve by the new IndexKey should have it's 
 * getIndexKeys() implemented to return a valid instance of the new IndexKey
 * inplementation that is correct for the instance. The class should also have 
 * matchesKey() inplemented to check that an IndexKey matches.
 *
 * You may also wish to create a static method in the class you are wanting to
 * get that hides the fact that an IndexKey is used and just accepts simple
 * parameters and builds the IndexKey behind the scenes.
 * Eg: PassPhrase.findPassPhraseByUserName()
 * 
 * @author Jon Maber
 * @author buckett
 * @see org.bodington.database.PersistentObject#getIndexKeys()
 * @see org.bodington.database.PersistentObject#matchesKey(IndexKey)
 * @see org.bodington.util.SoftCache
 */
public interface IndexKey
    {
    
    /**
     * Then SQL WHERE clause that should be used when searching for this
     * index lookup. The SQL returned when run should only return 0 or 1 rows
     * in the table.
     * @return The WHERE clause that finds the object associated with the index.
     */
    public String whereClause();
    
    /**
     * If the index lookup returns a no object should this be cached.
     * @return <code>true</code> is null index lookups can be cached.
     */
    public boolean cacheNull();
    }