/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2001 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.control;

import java.util.Collection;
import java.util.List;
import java.util.Map;

import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSDictionary;
import net.wotonomy.foundation.NSMutableArray;
import net.wotonomy.foundation.NSMutableDictionary;
import net.wotonomy.foundation.NSSelector;
import net.wotonomy.foundation.internal.WotonomyException;

/**
 * EOFetchSpecification defines the parameters used to request objects from an
 * EOObjectStore. They are commonly created and passed to a EODataSource which
 * fetches from its EOEditingContext, which passes the call up to its root
 * EOObjectStore's objectsWithFetchSpecification method.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 894 $
 */
public class EOFetchSpecification implements EOKeyValueArchiving {
	private boolean fetchesRawRows;
	private String entityName;
	private NSDictionary hints;
	private boolean deep;
	private int fetchLimit;
	private boolean locksObjects;
	private NSArray prefetchingRelationshipKeyPaths;
	private boolean promptsAfterFetchLimit;
	private EOQualifier qualifier;
	private NSArray rawRowKeyPaths;
	private boolean refreshesRefetchedObjects;
	private boolean requiresAllQualifierBindingVariables;
	private NSArray sortOrderings;
	private boolean distinct;

	/**
	 * Default constructor initializes internal state.
	 */
	public EOFetchSpecification() {
		fetchesRawRows = false;
		entityName = null;
		hints = null;
		deep = true;
		fetchLimit = 0;
		locksObjects = false;
		prefetchingRelationshipKeyPaths = null;
		promptsAfterFetchLimit = false;
		qualifier = null;
		rawRowKeyPaths = null;
		refreshesRefetchedObjects = false;
		requiresAllQualifierBindingVariables = false;
		sortOrderings = null;
		distinct = false;
	}

	/**
	 * Constructs a fetch specification for the specified entity type using the
	 * specified qualifier and sort ordering.
	 */
	public EOFetchSpecification(String anEntityName, EOQualifier aQualifier, List aSortOrderingList) {
		this();
		entityName = anEntityName;
		qualifier = aQualifier;
		sortOrderings = new NSArray((Collection) aSortOrderingList);
	}

	/**
	 * Constructs a fetch specification for the specified entity type using the
	 * specified qualifier and sort ordering, distinct flag, deep flag, and hints
	 * dictionary.
	 */
	public EOFetchSpecification(String anEntityName, EOQualifier aQualifier, NSArray aSortOrderingList,
			boolean usesDistinct, boolean isDeep, Map aHintMap) {
		this();
		entityName = anEntityName;
		qualifier = aQualifier;
		sortOrderings = new NSArray((Collection) aSortOrderingList);
		distinct = usesDistinct;
		deep = isDeep;
		hints = new NSMutableDictionary((Map) aHintMap);
	}

	/**
	 * Convenience to return the named fetch specification from the class
	 * description corresponding to the specified entity name. Returns null if
	 * either entityName or spec name cannot be resolved.
	 */
	public static EOFetchSpecification fetchSpecificationNamed(String name, String entityName) {
		EOClassDescription classDesc = EOClassDescription.classDescriptionForEntityName(entityName);
		if (classDesc == null)
			return null;
		return classDesc.fetchSpecificationNamed(name);
	}

	/**
	 * Implemented to return a new fetch specification that is a deep copy of this
	 * one.
	 */
	public Object clone() {
		EOFetchSpecification clone = new EOFetchSpecification();

		clone.fetchesRawRows = this.fetchesRawRows;
		clone.entityName = this.entityName;
		if (this.hints != null)
			clone.hints = new NSDictionary((Map) this.hints);
		clone.deep = this.deep;
		clone.locksObjects = this.locksObjects;
		if (this.prefetchingRelationshipKeyPaths != null)
			clone.prefetchingRelationshipKeyPaths = new NSArray((List) prefetchingRelationshipKeyPaths);
		clone.promptsAfterFetchLimit = this.promptsAfterFetchLimit;
		if (this.qualifier != null)
			clone.qualifier = this.qualifier; // FIXME: probably should clone?
		if (this.rawRowKeyPaths != null)
			clone.rawRowKeyPaths = new NSArray((List) this.rawRowKeyPaths);
		clone.refreshesRefetchedObjects = this.refreshesRefetchedObjects;
		clone.requiresAllQualifierBindingVariables = this.requiresAllQualifierBindingVariables;
		if (this.sortOrderings != null)
			clone.sortOrderings = new NSArray((List) this.sortOrderings);
		clone.distinct = this.distinct;

		return clone;
	}

	/**
	 * Returns the name of the entity fetched by this fetch spec.
	 */
	public String entityName() {
		return entityName;
	}

	/**
	 * Returns the current fetch limit. A fetch limit of zero indicates no fetch
	 * limit. Zero is the default.
	 */
	public int fetchLimit() {
		return fetchLimit;
	}

	/**
	 * Returns whether this fetch spec will fetch raw rows. Default is false.
	 */
	public boolean fetchesRawRows() {
		return fetchesRawRows;
	}

	/**
	 * Returns a fetch specification that resolves the bindings in the specified
	 * map.
	 */
	public EOFetchSpecification fetchSpecificationWithQualifierBindings(Map aBindingMap) {
		throw new WotonomyException("Not implemented yet");
	}

	/**
	 * Returns a Map containing the hints used by this fetch specification, or null
	 * if no hints have been specified.
	 */
	public NSDictionary hints() {
		if (hints == null)
			return null;
		return new NSDictionary((NSDictionary) hints);
	}

	/**
	 * Returns whether entities related to the primary entities are fetched by this
	 * fetch spec. If true, all relationships whose destinations meet the qualifier
	 * criteria will be returned in addition to primary results. If false, only the
	 * primary entities will be returned. Default is true.
	 */
	public boolean isDeep() {
		return deep;
	}

	/**
	 * Returns whether this data source should lock objects that are fetched.
	 * Default is false.
	 */
	public boolean locksObjects() {
		return locksObjects;
	}

	/***
	 * Returns a List of relationships for the fetched objects that should also be
	 * fetched, or null if no such list has been specified. Use this to avoid
	 * additional calls to the server to fetch relationships that you know you will
	 * use. NOTE: wotonomy allows you to specify non-relational keys as well.
	 */
	public NSArray prefetchingRelationshipKeyPaths() {
		return prefetchingRelationshipKeyPaths;
	}

	/**
	 * Returns whether the user should be prompted to continue when the fetch limit
	 * has been exceeded. Default is false.
	 */
	public boolean promptsAfterFetchLimit() {
		return promptsAfterFetchLimit;
	}

	/**
	 * Returns the qualifier used by this fetch specification, or null if none has
	 * been specified.
	 */
	public EOQualifier qualifier() {
		return qualifier;
	}

	/**
	 * Returns a List of keys or key paths for which values should be returned when
	 * fetching raw rows, or null if no raw row key paths have been specified.
	 */
	public NSArray rawRowKeyPaths() {
		return rawRowKeyPaths;
	}

	/**
	 * Returns whether fetched objects should replace modified versions already
	 * fetched into an editing context. If true, those changes will be lost. Default
	 * is false.
	 */
	public boolean refreshesRefetchedObjects() {
		return refreshesRefetchedObjects;
	}

	/**
	 * Returns whether all qualifier bindings must be specified in order to fetch.
	 * If true, an exception is thrown if unspecified bindings exist. If false,
	 * unspecified bindings will be removed from the qualifier. Default is false.
	 */
	public boolean requiresAllQualifierBindingVariables() {
		return requiresAllQualifierBindingVariables;
	}

	/**
	 * Sets the name of the entity fetched by this spec.
	 */
	public void setEntityName(String aName) {
		entityName = aName;
	}

	/**
	 * Sets whether this fetch spec will return raw rows.
	 */
	public void setFetchesRawRows(boolean shouldFetchRawRows) {
		fetchesRawRows = shouldFetchRawRows;
	}

	/**
	 * Sets the limit on the number of records returned for this fetch spec. Zero
	 * indicates no limit on fetches.
	 */
	public void setFetchLimit(int aLimit) {
		fetchLimit = aLimit;
	}

	/**
	 * Sets the hints passed by this fetch spec.
	 */
	public void setHints(Map aHintMap) {
		if (aHintMap == null) {
			hints = null;
		} else {
			hints = new NSDictionary((Map) aHintMap);
		}
	}

	/**
	 * Sets whether this fetch specification fetches deeply.
	 */
	public void setIsDeep(boolean isDeep) {
		deep = isDeep;
	}

	/**
	 * Sets whether this fetch spec locks objects that are returned by the fetch.
	 */
	public void setLocksObjects(boolean shouldLockObjects) {
		locksObjects = shouldLockObjects;
	}

	/**
	 * Sets the prefetch key paths that should be used as an optimization hint to
	 * the server. NOTE: wotonomy allows you to specify non-relationship keys as
	 * well.
	 */
	public void setPrefetchingRelationshipKeyPaths(List aKeyPathList) {
		if (aKeyPathList == null) {
			prefetchingRelationshipKeyPaths = null;
		} else {
			prefetchingRelationshipKeyPaths = new NSArray((List) aKeyPathList);
		}
	}

	/**
	 * Sets whether the user should be prompted when the fetch limit has been
	 * reached.
	 */
	public void setPromptsAfterFetchLimit(boolean shouldPrompt) {
		promptsAfterFetchLimit = shouldPrompt;
	}

	/**
	 * Sets the qualifier used by this fetch specification.
	 */
	public void setQualifier(EOQualifier aQualifier) {
		qualifier = aQualifier;
	}

	/**
	 * Sets the key paths to be returned if this fetch spec is returning raw rows.
	 */
	public void setRawRowKeyPaths(List aKeyPathList) {
		if (aKeyPathList == null) {
			rawRowKeyPaths = null;
		} else {
			rawRowKeyPaths = new NSArray((List) aKeyPathList);
		}
	}

	/**
	 * Sets whether modified objects in an editing context should be replaced by
	 * newer versions returned by this fetch spec.
	 */
	public void setRefreshesRefetchedObjects(boolean shouldRefresh) {
		refreshesRefetchedObjects = shouldRefresh;
	}

	/**
	 * Sets whether this fetch spec should require all bindings to be resolved
	 * before executing.
	 */
	public void setRequiresAllQualifierBindingVariables(boolean shouldRequireAll) {
		requiresAllQualifierBindingVariables = shouldRequireAll;
	}

	/**
	 * Sets the sort orderings used by this fetch spec.
	 */
	public void setSortOrderings(List aSortList) {
		if (aSortList == null) {
			sortOrderings = null;
		} else {
			sortOrderings = new NSArray((List) aSortList);
		}
	}

	/**
	 * Sets whether this fetch spec should return only distinct objects.
	 */
	public void setUsesDistinct(boolean shouldUseDistinct) {
		distinct = shouldUseDistinct;
	}

	/**
	 * Returns a List of the sort orderings used by this fetch spec, or null if none
	 * have been specified.
	 */
	public NSArray sortOrderings() {
		return sortOrderings;
	}

	/**
	 * Returns a string representation of this fetch specification.
	 */
	public String toString() {
		return "[FetchSpecification:qualifier=(" + qualifier + "),sortOrderings=" + sortOrderings + "]";
	}

	/**
	 * Returns whether this fetch specification will return only one reference to
	 * each distinct object returned by the fetch. Default is false.
	 */
	public boolean usesDistinct() {
		return distinct;
	}

	public void encodeWithKeyValueArchiver(EOKeyValueArchiver arch) {
		arch.encodeObject("EOFetchSpecification", "class");
		arch.encodeObject(entityName(), "entityName");
		arch.encodeInt(fetchLimit(), "fetchLimit");

		// flags
		if (isDeep())
			arch.encodeObject("YES", "isDeep");
		arch.encodeObject(qualifier(), "qualifier");
		if (refreshesRefetchedObjects())
			arch.encodeObject("YES", "refreshesRefetchedObjects");
		if (locksObjects())
			arch.encodeObject("YES", "locksObjects");
		if (fetchesRawRows())
			arch.encodeObject("YES", "fetchesRawRows");
		if (promptsAfterFetchLimit())
			arch.encodeObject("YES", "promptsAfterFetchLimit");
		if (requiresAllQualifierBindingVariables())
			arch.encodeObject("YES", "requiresAllQualifierBindingVariables");
		if (usesDistinct())
			arch.encodeObject("YES", "usesDistinct");

		// encode arrays
		if (sortOrderings() != null) {
			NSMutableArray arr = new NSMutableArray(sortOrderings().count());
			for (int i = 0; i < sortOrderings.count(); i++) {
				EOSortOrdering so = (EOSortOrdering) sortOrderings().objectAtIndex(i);
				EOKeyValueArchiver ar2 = new EOKeyValueArchiver();
				so.encodeWithKeyValueArchiver(ar2);
				arr.addObject(ar2.dictionary());
			}
			arch.encodeObject(arr, "sortOrderings");
		}
		if (rawRowKeyPaths != null && rawRowKeyPaths.count() > 0)
			arch.encodeObject(rawRowKeyPaths, "rawRowKeyPaths");
		if (prefetchingRelationshipKeyPaths != null && prefetchingRelationshipKeyPaths.count() > 0)
			arch.encodeObject(rawRowKeyPaths, "prefetchingRelationshipKeyPaths");
		if (hints != null && hints.count() > 0)
			arch.encodeObject(hints, "hints");
	}

	public static Object decodeWithKeyValueUnarchiver(EOKeyValueUnarchiver unarch) {
		EOFetchSpecification fs = new EOFetchSpecification();
		fs.setEntityName((String) unarch.decodeObjectForKey("entityName"));
		fs.setFetchLimit(unarch.decodeIntForKey("fetchLimit"));
		fs.setIsDeep(unarch.decodeBoolForKey("isDeep"));
		fs.setRefreshesRefetchedObjects(unarch.decodeBoolForKey("refreshesRefetchedObjects"));

		// Sort orderings
		NSArray arr = (NSArray) unarch.decodeObjectForKey("sortOrderings");
		if (arr != null && arr.count() > 0) {
			NSMutableArray orderings = new NSMutableArray(arr.count());
			for (int i = 0; i < arr.count(); i++) {
				NSDictionary so = (NSDictionary) arr.objectAtIndex(i);
				String selname = (String) so.objectForKey("selectorName");
				NSSelector selector = EOSortOrdering.CompareAscending;
				if (selname.startsWith("compareDescending"))
					selector = EOSortOrdering.CompareDescending;
				else if (selname.startsWith("compareCaseInsensitiveAscending"))
					selector = EOSortOrdering.CompareCaseInsensitiveAscending;
				else if (selname.startsWith("compareCaseInsensitiveDescending"))
					selector = EOSortOrdering.CompareCaseInsensitiveDescending;
				EOSortOrdering eoso = new EOSortOrdering((String) so.objectForKey("key"), selector);
				orderings.addObject(eoso);
			}
			fs.setSortOrderings(orderings);
		}
		// raw rows
		arr = (NSArray) unarch.decodeObjectForKey("rawRowKeyPaths");
		if (arr != null && arr.count() > 0) {
			fs.setFetchesRawRows(true);
			fs.setRawRowKeyPaths(arr);
		}
		// qualifier
		fs.setQualifier((EOQualifier) unarch.decodeObjectForKey("qualifier"));
		return fs;
	}

}

/*
 * $Log$ Revision 1.2 2006/02/16 16:47:14 cgruber Move some classes in to
 * "internal" packages and re-work imports, etc.
 *
 * Also use UnsupportedOperationExceptions where appropriate, instead of
 * WotonomyExceptions.
 *
 * Revision 1.1 2006/02/16 13:19:57 cgruber Check in all sources in
 * eclipse-friendly maven-enabled packages.
 *
 * Revision 1.4 2003/08/11 18:19:01 chochos encoding/decoding with
 * EOKeyValueArchiving now works properly
 *
 * Revision 1.3 2003/08/09 01:22:20 chochos implements EOKeyValueArchiving (and
 * unarchiving)
 *
 * Revision 1.2 2001/11/24 17:32:57 mpowers We now have a real implementation.
 *
 * Revision 1.1 2001/02/05 03:45:37 mpowers Starting work on EOEditingContext.
 *
 *
 */