/*
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 net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSDictionary;

/**
* EOEnterpriseObject defines the required methods a data object
* must implement to take full advantage of the control package.
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 894 $
*/
public interface EOEnterpriseObject
    extends EOKeyValueCodingAdditions,
            EORelationshipManipulation,
            EODeferredFaulting,
            EOValidation
{
    /**
    * Returns a List of all property keys defined on this object.
    * This includes both attributes and relationships.
    */
    NSArray allPropertyKeys();
    
    /**
    * Returns a list of all attributes defined on this object.
    * Attributes are all properties that are not relationships.
    */
    NSArray attributeKeys();
    
    //void awakeFromClientUpdate(EOEditingContext aContext)
    
    /**
    * Called when the object has first been fetched into the 
    * specified editing context.
    */
    void awakeFromFetch(EOEditingContext anEditingContext);
    
    /**
    * Called when the object has been inserted into the 
    * specified editing context.
    */
    void awakeFromInsertion(EOEditingContext anEditingContext);
    
    /**
    * Returns a Map representing the delta of the current state
    * from the state represented in the specified snapshot.
    * The result will contain only the keys that have changed
    * and their values.  Relationship keys will map to an NSArray
    * that contains an NSArray of added objects and an NSArray
    * of removed objects, in that order.
    */
    NSDictionary changesFromSnapshot(NSDictionary snapshot);
    
    /**
    * Returns a class description for this object.
    */
    EOClassDescription classDescription();
    
    /**
    * Returns a class description for the object at the 
    * other end of the specified relationship key.
    */
    EOClassDescription classDescriptionForDestinationKey(String aKey);
    
    /**
    * Clears all property values for this object.
    * This method is called to clean-up an object that
    * will no longer be used, and implementations should
    * ensure that all references are set to null to 
    * prevent problems with garbage-collection.
    */ 
    void clearProperties();
    
    /**
    * Returns the delete rule constant defined on EOClassDescription
    * for the relationship defined by the specified key.
    */
    int deleteRuleForRelationshipKey(String aRelationshipKey);
    
    /**
    * Returns the editing context in which this object is registered.
    */
    EOEditingContext editingContext();
    
    /**
    * Returns the name of the entity that this object represents.
    */
    String entityName();
    
    /**
    * Returns a String containing all property keys and values for
    * this object.  Relationships should be represented by calling
    * eoShallowDescription() on the object.
    */
    String eoDescription();
    
    /**
    * Returns a String containing all attribute keys and values for
    * this object.  Relationships are not included.
    */
    String eoShallowDescription();
    
    /**
    * Returns the key used to reference this object on the 
    * object at the other end of the specified relationship.
    */
    String inverseForRelationshipKey(String aRelationshipKey);
    
    //Object invokeRemoteMethod( 
    //	String aMethodName, Class[] aTypeArray Object[] anArgumentArray)
    
    /**
    * Returns whether the specified relationship key represents
    * a to-many relationship.
    */
    boolean isToManyKey(String aKey);
    
    /**
    * Returns whether the objects at the other end of the specified
    * relationship should be deleted when this object is deleted.
    */
    boolean ownsDestinationObjectsForRelationshipKey(String aKey);
    
    //void prepareValuesForClient()
    
    /**
    * Called to perform the delete propagation for this object
    * on the specified editing context.  All relationships 
    * should be processed according to their corresponding 
    * delete rule.
    */
    void propagateDeleteWithEditingContext(EOEditingContext aContext);
    
    /**
    * Applies the changes from the specified snapshot to
    * this object.  
    * @see #changesFromSnapshot(NSDictionary)
    */
    void reapplyChangesFromDictionary(NSDictionary aDeltaSnapshot);
    
    /**
    * Returns a snapshot of the current state of this object.
    * All property keys are mapped to their values; nulls are
    * represented by NSNull.
    */
    NSDictionary snapshot();
    
    /**
    * Returns a List of the to-many relationship keys
    * for this object.
    */ 
    NSArray toManyRelationshipKeys();
    
    /**
    * Returns a List of the to-one relationship keys
    * for this object.
    */
    NSArray toOneRelationshipKeys();
    
    /**
    * Applies the specified snapshot to this object,
    * converting NSNulls to null and calling 
    * takeStoredValueForKey for each key in the Map.
    */
    void updateFromSnapshot(NSDictionary aSnapshot);
    
    /**
    * Returns a short, stateful string representation
    * of this object.
    */
    String userPresentableDescription();
    
    /**
    * This method should be implemented to call 
    * EOObserverCenter.objectWillChange( this ),
    * and it should be called by each setter method
    * on this object before changes are made to the
    * object's internal state.
    */
    void willChange();
}

/*
 * $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.1  2001/11/13 04:13:59  mpowers
 * Added interfaces needed to begin work on EOCustomObject.
 *
 *
 */