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