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

import net.wotonomy.foundation.NSArray;

/**
 * EODataSource is used by EODisplayGroup.fetch() to retrieve a list of objects
 * to display. When a display group has a data source, the display group will
 * use the data source to populate the object list and to create new objects to
 * be displayed in the list, and will update the data source when objects are
 * inserted or removed from the list. <br>
 * <br>
 *
 * In certain cases, as when a display group needs to populate a child display
 * group to show a one-to-many relationship, the display group will call
 * dataSourceQualifiedByKey to return a new data source that can vend objects
 * associated with the specified key and then call qualifyWithRelationshipKey to
 * specify the object and key that are the source of the child relationship.
 * <br>
 * <br>
 *
 * Concrete subclasses are expected to override fetch() and are required to
 * override insertObject and removeObject.
 *
 * @author michael@mpowers.net
 * @author $Author: cgruber $
 * @version $Revision: 894 $
 */
public abstract class EODataSource {
	/**
	 * Creates a new object. You should call insertObject() to insert the new object
	 * into this data source. This implementation attempts to create a new instance
	 * of the class returned by classDescriptionForObjects(). Override to return an
	 * object specific to your implementation.
	 * 
	 * @return The newly created object, or null if new objects are not supported by
	 *         this data source.
	 * @see #classDescriptionForObjects
	 */
	public Object createObject() {
		Object result = null;
		EOClassDescription c = classDescriptionForObjects();
		if (c != null) {
			result = c.createInstanceWithEditingContext(editingContext(), null);
		}
		return result;
	}

	/**
	 * Inserts the specified object into this data source.
	 */
	public abstract void insertObject(Object anObject);

	/**
	 * Deletes the specified object from this data source.
	 */
	public abstract void deleteObject(Object anObject);

	/**
	 * Returns the editing context for this data source, or null if no editing
	 * context is used. This implementation returns null.
	 */
	public EOEditingContext editingContext() {
		return null;
	}

	/**
	 * Returns a List containing the objects in this data source. This
	 * implementation returns null.
	 */
	public NSArray fetchObjects() {
		return null;
	}

	/**
	 * Returns a data source that is capable of manipulating objects of the type
	 * returned by applying the specified key to objects vended by this data source.
	 * 
	 * @see #qualifyWithRelationshipKey
	 */
	public abstract EODataSource dataSourceQualifiedByKey(String aKey);

	/**
	 * Restricts this data source to vend those objects that are associated with the
	 * specified key on the specified object.
	 */
	public abstract void qualifyWithRelationshipKey(String aKey, Object anObject);

	/**
	 * Returns the description of the class of the objects that is vended by this
	 * data source, or null if this cannot be determined. This implementation
	 * returns null.
	 */
	public EOClassDescription classDescriptionForObjects() {
		return null;
	}

}

/*
 * $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.5 2001/05/21 14:02:44 mpowers Corrected javadoc.
 *
 * Revision 1.4 2001/04/27 23:37:20 mpowers Now using EOClassDescription in the
 * EODataSource class, as we should.
 *
 * Revision 1.3 2001/02/27 23:11:07 mpowers Removed object registration from
 * createObject().
 *
 * Revision 1.2 2001/02/16 18:34:19 mpowers Implementing nested contexts.
 *
 * Revision 1.1.1.1 2000/12/21 15:46:38 mpowers Contributing wotonomy.
 *
 * Revision 1.3 2000/12/20 16:25:34 michael Added log to all files.
 *
 *
 */