/* ======================================================================
   Parts Copyright 2006 University of Leeds, Oxford University, University of the Highlands and Islands.

   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 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();
    }