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

/*
Wotonomy: OpenStep design patterns for pure Java applications.
Copyright (C) 2001 Intersect Software Corporation

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.NSSet;
import net.wotonomy.foundation.internal.WotonomyException;

/**
* EOCustomObject implements all the necessary interfaces to
* receive first-class treatment from the control framework.
* The implementation delegates as much class meta-behavior as
* possible to EOClassDescription, letting subclasses
* focus exclusively on business logic while still allowing 
* them to customize as much class behavior as needed.
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 894 $
*/
public class EOCustomObject
 implements EOEnterpriseObject,
            EOKeyValueCodingAdditions,
            EODeferredFaulting,
            EORelationshipManipulation,
            EOValidation
{
    private transient static EOClassDescription classDescription;
    private transient EOEditingContext editingContext;
    
    // static configuration

    /**
    * Specifies whether the implementation of EOKeyValueCoding
    * is permitted to access field directly.  This implementation
    * returns true; subclasses may override to customize this behavior. 
    */
    public static boolean canAccessFieldsDirectly()
    {
        return true;
    }
    
    /**
    * Specifies whether the implementation of EOKeyValueCoding
    * is permitted to access private accessors.  This implementation
    * returns true; subclasses may override to customize this behavior. 
    */
    public static boolean shouldUseStoredAccessors()
    {
        return true;
    }
    
    /**
    * Specifies whether deferred faults should be used.  This implementation
    * returns false; subclasses may override to customize this behavior. 
    */
    public static boolean usesDeferredFaultCreation()
    {
        return false;
    }
    
    // constructors
    
    /**
    * Default constructor initializes private state.
    * EditingContext and ClassDescription are set to null.
    */
    public EOCustomObject()
    {
        editingContext = null;
        classDescription = null;
    }
    
    /**
    * Preferred constructor, specifying an editing context,
    * a class description, and a global id, any or all of which
    * may be null.  Subclasses should invoke this constructor.
    */
    public EOCustomObject(
        EOEditingContext aContext, 
        EOClassDescription aClassDescription, 
        EOGlobalID aGlobalID )
    {
        editingContext = aContext;
        classDescription = aClassDescription;
    }
    
    // interface EOEnterpriseObject

    /**
    * Returns a List of all property keys defined on this object.
    * This includes both attributes and relationships.
    * This implementation returns the union of attributeKeys,
    * toOneRelationshipKeys, and toManyRelationshipKeys.
    */
    public NSArray allPropertyKeys()
    {
        NSSet union = new NSSet();
        union.addAll( attributeKeys() );
        union.addAll( toOneRelationshipKeys() );
        union.addAll( toManyRelationshipKeys() );
        return new NSArray( (Collection) union );
    }
    
    /**
    * Returns a list of all attributes defined on this object.
    * Attributes are all properties that are not relationships.
    * This implementation retrieves the keys from the class
    * description.
    */
    public NSArray attributeKeys()
    {
        return classDescription().attributeKeys();
    }
    
    //void awakeFromClientUpdate(EOEditingContext aContext)
    
    /**
    * Called when the object has first been fetched into the 
    * specified editing context.  This implementation calls
    * awakeObjectFromFetch on the class description.
    */
    public void awakeFromFetch(EOEditingContext anEditingContext)
    {
        classDescription().awakeObjectFromFetch( this, anEditingContext );
    }
    
    /**
    * Called when the object has been inserted into the 
    * specified editing context.  This implementation calls
    * awakeObjectFromInsertion on the class description.
    */
    public void awakeFromInsertion(EOEditingContext anEditingContext)
    {
        classDescription().awakeObjectFromInsertion( this, 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.
    */
    public NSDictionary changesFromSnapshot(NSDictionary snapshot)
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns a class description for this object.
    * Calls EOClassDescription.classDescriptionForClass.
    */
    public EOClassDescription classDescription()
    {
        if ( classDescription == null )
        {
            classDescription = EOClassDescription.classDescriptionForClass( getClass() );
            if ( classDescription == null )
            {
                throw new WotonomyException( 
                    "No class description found for class: " + getClass() );
            }
        }
        return classDescription;
    }
    
    /**
    * Returns a class description for the object at the 
    * other end of the specified relationship key.
    * This implementation calls to the classDescription.
    */
    public EOClassDescription classDescriptionForDestinationKey(String aKey)
    {
        return classDescription().classDescriptionForDestinationKey( 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.
    */ 
    public void clearProperties()
    {
        //FIXME: clear properties here
    }
    
    /**
    * Returns the delete rule constant defined on EOClassDescription
    * for the relationship defined by the specified key.
    * This implementation calls to the classDescription.
    */
    public int deleteRuleForRelationshipKey(String aRelationshipKey)
    {
        return classDescription().deleteRuleForRelationshipKey( aRelationshipKey );
    }
    
    /**
    * Returns the editing context in which this object is registered.
    */
    public EOEditingContext editingContext()
    {
        return editingContext;
    }
    
    /**
    * Returns the name of the entity that this object represents.
    */
    public String entityName()
    {
        return classDescription().entityName();
    }
    
    /**
    * Returns a String containing all property keys and values for
    * this object.  Relationships should be represented by calling
    * eoShallowDescription() on the object.
    */
    public String eoDescription()
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns a String containing all attribute keys and values for
    * this object.  Relationships are not included.
    */
    public String eoShallowDescription()
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns the key used to reference this object on the 
    * object at the other end of the specified relationship.
    * This implementation calls to the class description.
    */
    public String inverseForRelationshipKey(String aRelationshipKey)
    {
        return classDescription().inverseForRelationshipKey( aRelationshipKey );
    }
    
    //Object invokeRemoteMethod( 
    //	String aMethodName, Class[] aTypeArray Object[] anArgumentArray)
    
    /**
    * Returns whether the specified relationship key represents
    * a to-many relationship.
    */
    public boolean isToManyKey(String aKey)
    {
        return toManyRelationshipKeys().containsObject( aKey );
    }
    
    /**
    * Returns whether the objects at the other end of the specified
    * relationship should be deleted when this object is deleted.
    * This implementation calls to the class description.
    */
    public boolean ownsDestinationObjectsForRelationshipKey(String aKey)
    {
        return classDescription().ownsDestinationObjectsForRelationshipKey( 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.
    * This implementation calls to the class description.
    */
    public void propagateDeleteWithEditingContext(EOEditingContext aContext)
    {
        classDescription().propagateDeleteForObject( this, aContext );
    }
    
    /**
    * Applies the changes from the specified snapshot to
    * this object.  
    * @see #changesFromSnapshot(NSDictionary)
    */
    public void reapplyChangesFromDictionary(NSDictionary aDeltaSnapshot)
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns a snapshot of the current state of this object.
    * All property keys are mapped to their values; nulls are
    * represented by NSNull.
    */
    public NSDictionary snapshot()
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns a List of the to-many relationship keys
    * for this object.
    * This implementation calls to the class description.
    */ 
    public NSArray toManyRelationshipKeys()
    {
        return classDescription().toManyRelationshipKeys();
    }
    
    /**
    * Returns a List of the to-one relationship keys
    * for this object.
    * This implementation calls to the class description.
    */
    public NSArray toOneRelationshipKeys()
    {
        return classDescription().toOneRelationshipKeys();
    }
    
    /**
    * Applies the specified snapshot to this object,
    * converting NSNulls to null and calling 
    * takeStoredValueForKey for each key in the Map.
    */
    public void updateFromSnapshot(NSDictionary aSnapshot)
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns a short, stateful string representation
    * of this object.
    * This implementation calls to the class description.
    */
    public String userPresentableDescription()
    {
        return classDescription().userPresentableDescriptionForObject( this );
    }
    
    /**
    * This method should be called by each setter method
    * on this object before changes are made to the
    * object's internal state.  This implementation calls 
    * EOObserverCenter.notifyObserversObjectWillChange( this ),
    */
    public void willChange()
    {
        EOObserverCenter.notifyObserversObjectWillChange( this );
    }
    
    // interface EOKeyValueCoding
    
    /**
    * Returns the value for the specified property.
    * If the property does not exist, this method should
    * call handleQueryWithUnboundKey.
    */
    public Object valueForKey( String aKey )
    {
        return EOKeyValueCodingSupport.valueForKey( this, aKey );
    }

    /**
    * Sets the property to the specified value.
    * If the property does not exist, this method should
    * call handleTakeValueForUnboundKey.
    * If the property is of a type that cannot allow
    * null (e.g. primitive types) and aValue is null,
    * this method should call unableToSetNullForKey.
    */
    public void takeValueForKey( Object aValue, String aKey )
    {
        EOKeyValueCodingSupport.takeValueForKey( this, aValue, aKey );
    }

    /**
    * Returns the value for the private field that 
    * corresponds to the specified property.
    */
    public Object storedValueForKey( String aKey )
    {
        return EOKeyValueCodingSupport.storedValueForKey( this, aKey );
    }

    /**
    * Sets the the private field that corresponds to the 
    * specified property to the specified value.
    */
    public void takeStoredValueForKey( Object aValue, String aKey )
    {
        EOKeyValueCodingSupport.takeStoredValueForKey( this, aValue, aKey );
    }

    /**
    * Called by valueForKey when the specified key is
    * not found on this object.  Implementing classes 
    * should handle the specified value or otherwise 
    * throw an exception.
    */
    public Object handleQueryWithUnboundKey( String aKey )
    {
        return EOKeyValueCodingSupport.handleQueryWithUnboundKey( this, aKey );
    }

    /**
    * Called by takeValueForKey when the specified key
    * is not found on this object.  Implementing classes
    * should handle the specified value or otherwise 
    * throw an exception.
    */
    public void handleTakeValueForUnboundKey( Object aValue, String aKey )
    {
        EOKeyValueCodingSupport.handleTakeValueForUnboundKey( this, aValue, aKey );
    }

    /**
    * Called by takeValueForKey when the type of the
    * specified key is not allowed to be null, as is
    * the case with primitive types.  Implementing 
    * classes should handle this case appropriately
    * or otherwise throw an exception.
    */
    public void unableToSetNullForKey( String aKey )
    {
        EOKeyValueCodingSupport.unableToSetNullForKey( this, aKey );
    }

    // interface EOKeyValueCodingAdditions
    
    /**
    * Returns the value for the specified key path, which is
    * a series of keys delimited by ".", for example:
    * "createTime.year.length".
    */
    public Object valueForKeyPath( String aKeyPath )
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    /**
    * Sets the value for the specified key path, which is
    * a series of keys delimited by ".", for example:
    * "createTime.year.length".
    * The value is set for the last object referenced by
    * the key path.
    */
    public void takeValueForKeyPath( Object aValue, String aKeyPath )
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns a Map of the specified keys to their values,
    * each of which might be obtained by calling valueForKey.
    */
    public NSDictionary valuesForKeys( List aKeyList )
    {
        return KeyValueCodingUtilities.valuesForKeys( this, aKeyList );
    }
    
    /**
    * Takes the keys from the specified map as properties
    * and applies the corresponding values, each of which
    * might be set by calling takeValueForKey.
    */
    public void takeValuesFromDictionary( Map aMap )
    {
         KeyValueCodingUtilities.takeValuesFromDictionary( this, aMap );
    }
    
    // interface EOFaulting
    
    /**
    * Called by EOFaultHandler to prepare the object to be turned into a fault. 
    */
    public void clearFault()
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns this object's EOFaultHandler.
    */
    public EOFaultHandler faultHandler()
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Returns whether this object is currently a fault.
    * Returns true if this object has not yet retrieved any values.
    */
    public boolean isFault()
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Turns this object into a fault using the specified fault handler.
    */
    public void turnIntoFault( EOFaultHandler aFaultHandler )
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Called to completely fire the fault, reading all attributes.
    * This method may be implemented to call willRead(null).
    */
    public void willRead()
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    /**
    * Called to fire the fault for the specified key.  
    * The fault manager is required to populate the specified key
    * with a value, and may populate any or all of the other values
    * on this object.  A null key will populate all values on the object.
    * NOTE: This method is not part of the specification.
    */
    public void willRead( String aKey )
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    // interface EODeferredFaulting
    
    /**
    * Returns a fault for the specified deferred fault.
    */
	public Object willReadRelationship( Object anObject )
    {
        throw new WotonomyException( "Not implemented yet." );
    }
    
    // interface EORelationshipManipulation
    
    /**
    * Adds the specified object to the relationship on this
    * object specified by the key.  For to-one relationships,
    * this operation is the same as valueForKey.
    */
    public void addObjectToPropertyWithKey( 
        Object anObject, String aKey )
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    /**
    * Removes the specified object from the relationship on
    * this object specified by the key.  For to-one relationships,
    * this operation is the same as takeValueForKey with a null
    * value.
    */
    public void removeObjectFromPropertyWithKey( 
        Object anObject, String aKey )
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    /**
    * As addObjectToProperty with key, but also performs the
    * reciprocal operation on the other side of the relationship.
    */
    public void addObjectToBothSidesOfRelationshipWithKey( 
        EORelationshipManipulation anObject, String aKey )
    {
        throw new WotonomyException( "Not implemented yet." );
    }
        
    /**
    * As removeObjectFromPropertyWithKey with key, but also performs the
    * reciprocal operation on the other side of the relationship.
    */
    public void removeObjectFromBothSidesOfRelationshipWithKey( 
        EORelationshipManipulation anObject, String aKey )
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    // interface EOValidation
    
    /**
    * Validates this object for delete.
    * Throws an exception if this object cannot be deleted.
    * This implementation calls to the class description.
    */
    public void validateForDelete()
    {
        classDescription().validateObjectForDelete( this );
    }
    
    /**
    * Validates this object for insertion into the external store.
    * Throws an exception if this object cannot be inserted.
    * Validations here should be specific to insertion.
    * This implementation calls validateForSave(). 
    */
    public void validateForInsert()
    {
        validateForSave();
    }
    
    /**
    * Validates this object for a commit to the external store.
    * Throws an exception if this object cannot be committed.
    * Validations here are not specific to either inserts or updates.
    * This implementation calls to the class description.
    */
    public void validateForSave()
    {
        classDescription().validateObjectForSave( this );
    }
    
    /**
    * Validates this object for update to the external store.
    * Throws an exception if this object cannot be updated.
    * Validations here should be specific to updates.
    * This implementation calls validateForSave(). 
    */
    public void validateForUpdate()
    {
        validateForSave();
    }
}

/*
 * $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.3  2001/12/06 16:42:29  mpowers
 * Added appropriate constructor.
 *
 * Revision 1.2  2001/11/24 17:37:29  mpowers
 * Implemented static methods.
 *
 * Revision 1.1  2001/11/17 17:18:15  mpowers
 * Initial implementation of EOCustomObject.
 *
 *
 */