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