path: root/projects/net.wotonomy.persistence/src/main/java/net/wotonomy/control/EOFetchSpecification.java

/*
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.
 *
 *
 */