/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2000 Michael Powers

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, see http://www.gnu.org
*/

package net.wotonomy.datastore;

import java.io.Serializable;
import java.util.List;

/**
 * A DataIndex maintains a list of objects associated with values. The objects
 * can then be retrieved based on the values. This class should not be much more
 * complex than a simple map or list because the DataSoup is responsible for
 * populating it.
 */
public interface DataIndex extends Serializable {
	/**
	 * Gets the name of this index. The DataSoup uses this to uniquely refer to this
	 * index.
	 * 
	 * @return The name of this index.
	 */
	public String getName();

	/**
	 * The property managed by this index. This is the property used when the
	 * DataSoup builds and rebuilds this index.
	 * 
	 * @return The property managed by this index.
	 */
	public String getProperty();

	/**
	 * Adds an object to be associated with the specified value.
	 * 
	 * @param anObject A data object, usually but not always a DataKey.
	 * @param newValue The property value to be associated with the data object.
	 * @return The data object that was inserted, or null if an error occurred.
	 */
	public Object addObject(Object anObject, Object newValue);

	/**
	 * Updates an object previously associated with the specified value to be
	 * associated with the specified new value.
	 * 
	 * @param anObject A data object, usually but not always a DataKey.
	 * @param oldValue The value currently associated with the data object.
	 * @param newValue The value to be associated with the data object.
	 * @return The data object that was updated, or null if an error occurred.
	 */
	public Object updateObject(Object anObject, Object oldValue, Object newValue);

	/**
	 * Removes an object from the index.
	 * 
	 * @param anObject A data object, usually but not always a DataKey.
	 * @param oldValue The value currently associated with the data object.
	 * @return The data object that was removed, or null if not found or error.
	 */
	public Object removeObject(Object anObject, Object oldValue);

	/**
	 * Removes all objects from the index. Usually called before rebuilding the
	 * index.
	 */
	public void clear();

	/**
	 * Returns all objects in the index whose associated values fall between the two
	 * specified values, inclusive.
	 * 
	 * @param beginValue The beginning value, or null for all values up to an
	 *                   including the end key.
	 * @param endValue   The ending value, or null for all values since and
	 *                   including the begin key.
	 * @return A List of the matching objects, ordered in increasing value, or null
	 *         for invalid query parameters or other error.
	 */
	public List query(Object beginValue, Object endValue);

}

/*
 * $Log$ Revision 1.2 2006/02/19 16:26:19 cgruber Move non-unit-test code to
 * tests project Fix up code to work with proper imports Fix maven dependencies.
 *
 * Revision 1.1 2006/02/16 13:18:56 cgruber Check in all sources in
 * eclipse-friendly maven-enabled packages.
 *
 * Revision 1.1.1.1 2000/12/21 15:46:50 mpowers Contributing wotonomy.
 *
 * Revision 1.2 2000/12/20 16:25:35 michael Added log to all files.
 *
 *
 */