/*
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.HashMap;
import java.util.Map;

import net.wotonomy.foundation.NSArray;
import net.wotonomy.foundation.NSMutableArray;
import net.wotonomy.foundation.NSNotificationCenter;
import net.wotonomy.foundation.internal.Introspector;
import net.wotonomy.foundation.internal.WotonomyException;

/**
* EOClassDescription provides meta-information about a class
* and is used to customize certain behaviors within wotonomy
* and specifically within editing contexts and object stores.
* <br><br>
*
* The default implementation works for most well-formed java beans,
* but you will want to create your own subclass most typically
* to customize the toOne and toMany relationships for your
* class to ensure that an entire graph of objects is not 
* persisted in order to perist a single object.
* <br><br>
*
* The easiest way to register your subclass is to create it
* in the same package as the class it describes but with 
* a "ClassDesc" suffix.  For example, "my.package.MyEntity"
* would be described by "my.package.MyEntityClassDesc". <br><br>
* 
* Note that while the interface is the same, the implementation
* of this class differs substantially from the specification
* in order to be more useful for java classes.
*
* @author michael@mpowers.net
* @author $Author: cgruber $
* @version $Revision: 900 $
*/
public class EOClassDescription 
{
    /**
    * A delete rule specifying that object(s) that reference
    * this object should have those references set to null
    * when this object is deleted.
    */ 
    public static final int DeleteRuleNullify  = 0;
    
    /**
    * A delete rule specifying that object(s) referenced by
    * this object should also be deleted when this object
    * is deleted.
    */
    public static final int DeleteRuleCascade  = 1;
    
    /**
    * A delete rule specicying that this object should
    * not be allowed to be deleted if it references any
    * object(s).
    */
    public static final int DeleteRuleDeny     = 2;
    
    /**
    * A delete rule specifying that no action be taken
    * when this object is deleted.  This is the default.
    */
    public static final int DeleteRuleNoAction = 3;
    
    /**
    * Notification fired when a class description has been requested
    * for a class.  Observers should watch for this notification and
    * call registerClassDescription so that class descriptions can be 
    * loaded on-demand.
    * The notification's object is the requested class and the 
    * user info dictionary is null.
    */    
    public static final String ClassDescriptionNeededForClassNotification =
        "ClassDescriptionNeededForClassNotification";

    /**
    * Notification fired when a class description has been requested
    * for an entity name.  Observers should watch for this notification and
    * call registerClassDescription so that class descriptions can be 
    * loaded on-demand.
    * The notification's object is the requested name and the 
    * user info dictionary is null.
    */    
    public static final String ClassDescriptionNeededForEntityNameNotification = 
        "ClassDescriptionNeededForEntityNameNotification";

	public EOClassDescription() {
		super();
	}

    /**
    * Returns the class description that corresponds to the specified class.
    * If the class description has not already been loaded, a 
    * ClassDescriptionNeededForClassNotification is posted.
    * If the class description is still not found, the class' loader
    * is consulted for a class in the same package and named the same as the 
    * specified class but appended with "ClassDesc", e.g. "EmployeeObjectClassDesc".
    * If the class description is still not found, a class description is
    * returned that uses java bean introspection to provide reasonable values.
    */
    public static EOClassDescription classDescriptionForClass(
        Class aClass )
    {
        if ( classMap == null ) classMap = new HashMap();
        EOClassDescription result = (EOClassDescription) classMap.get( aClass );
        if ( result == null )
        {
            // if not found, post notification
            NSNotificationCenter.defaultCenter().postNotification(
                ClassDescriptionNeededForClassNotification, aClass, null );
            result = (EOClassDescription) classMap.get( aClass );
        }
        if ( result == null )
        {
            // if not found, look for similarly named class
            String className = aClass.getName() + ClassNameSuffix;
            Class classDesc;
            try
            {
                classDesc = aClass.getClassLoader().loadClass( className );
                if ( classDesc != null )
                {
                    result = (EOClassDescription) classDesc.newInstance();
                    registerClassDescription( result, aClass );
                }
            }
            catch ( Exception exc )
            {
                // ignore exceptions and resume   
            }
        }            
        if ( result == null )
        {
            // if not found, default to this class
            result = new EOClassDescription( aClass );
            registerClassDescription( result, aClass );
        }
        return result;
    }

    /**
    * Returns the class description that corresponds to the specified
    * entity name.  If the class description has not already been
    * loaded, a ClassDescriptionNeededForEntityNameNotification is posted.
    * Returns null if no class description can be found for the entity name.
    */
    public static EOClassDescription classDescriptionForEntityName(
        String aName )
    {
        if ( entityMap == null ) entityMap = new HashMap();
        EOClassDescription result = (EOClassDescription) entityMap.get( aName );
        if ( result == null )
        {
            // if not found, post notification
            NSNotificationCenter.defaultCenter().postNotification(
                ClassDescriptionNeededForEntityNameNotification, aName, null );
            result = (EOClassDescription) entityMap.get( aName );
        }            
        return result;
    }

    /**
    * Clears all cached class descriptions so that new requests
    * for class descriptions will be re-loaded on-demand.
    */ 
    public static void invalidateClassDescriptionCache()
    {
        classMap.clear();
        entityMap.clear();
    }

    /**
    * Registers the specified class descriptiong for the specified class.
    * Nulls are not allowed - to clear the cache call invalidateClassDescriptionCache().
    */
    public static void registerClassDescription( 
        EOClassDescription description, 
        Class aClass )
    {
        if ( classMap == null ) classMap = new HashMap();
        if ( entityMap == null ) entityMap = new HashMap();
        description.theClass = aClass;
        classMap.put( aClass, description );
        entityMap.put( description.entityName(), description );
    }

/*
    public static Object classDelegate()
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    public static void setClassDelegate(
        Object aDelegate)
    {
        throw new WotonomyException( "Not implemented yet." );
    }
*/
    
    /**
    * The string appended to the java class name when
    * searching the class path for an appropriate description.
    */
    private final static String ClassNameSuffix = "ClassDesc";

    private static Map classMap;
    private static Map entityMap;

    protected Class theClass;
    private NSMutableArray attributes;
    
    /**
    * Constructor may only be called by subclasses.
    */
    protected EOClassDescription( Class aClass )
    {
        theClass = aClass;
    }
    
    /**
    * Returns a List of all the attributes for this class.
    * This implementation reflects on the java class to produce
    * a list of attributes, and then removes those keys that
    * are returned by toOneRelationshipKeys and toManyRelationhipKeys.
    */
    public NSArray attributeKeys()
    {
        if ( attributes == null )
        {
            NSMutableArray readProperties = new NSMutableArray();
            String[] read = Introspector.getReadPropertiesForClass( theClass );
            for ( int i = 0; i < read.length; i++ )
            {
                readProperties.addObject( read[i] );
            }
    
            attributes = new NSMutableArray();
            String[] write = Introspector.getWritePropertiesForClass( theClass );
            for ( int i = 0; i < write.length; i++ )
            {
                attributes.addObject( write[i] );
            }
            
            // only use properties on both lists: read/write
            attributes.retainAll( readProperties );
            
            // remove relationship keys
            attributes.removeAll( toOneRelationshipKeys() );
            attributes.removeAll( toManyRelationshipKeys() );
        }
        return attributes;
    }

    /**
    * This method is called when the specified object has been
    * fetched into the specified editing context.  Fetch means
    * an object was fetched using a fetch specification - it is
    * not the same thing as an insertion.
    * This implementation does nothing.
    */
    public void awakeObjectFromFetch(
        Object object, 
        EOEditingContext anEditingContext )
    {
    }

    /**
    * This method is called when the specified object has been
    * inserted into the specified editing context.  Insertion
    * means an object was inserted by a display group - it does
    * not mean the same thing as a fetch.
    * This implementation does nothing.
    */
    public void awakeObjectFromInsertion( 
        Object object, 
        EOEditingContext anEditingContext )
    {
        // does nothing
    }

    /**
    * Returns the class decription for the object referenced
    * by the specified relationship key, or null if the
    * class description cannot be determined for that key.
    * This implementation returns null.
    */
    public EOClassDescription classDescriptionForDestinationKey(
        String detailKey )
    {
        return null;
    }

    /**
    * Creates a new instance of the class represented by this
    * class description, registering it with the specified 
    * editing context and global id.  The class description
    * may not keep references to the newly created object.
    * The editing context and/or the id may be null.
    * This implementation constructs a new instance of the class
    * and registers it with the specified editing context.
    * If the global id is specified, the object will be populated
    * with the appropriate data, otherwise the object will be 
    * treated as a newly inserted object.
    * If no editing context is specified, the global id is
    * ignored and the new instance of the class is returned.
    */
    public Object createInstanceWithEditingContext( 
        EOEditingContext anEditingContext, 
        EOGlobalID globalID )
    {
//System.out.println( "createInstanceWithEditingContext: " + this + " : " + theClass );
        Object result = null;
        try
        {
            result = theClass.newInstance();
            if ( anEditingContext != null )
            {
                if ( globalID != null )
                {
                    if ( result instanceof EOEnterpriseObject )
                    {
                        ((EOEnterpriseObject)result).awakeFromFetch( anEditingContext );
                    }
                    // register in editing context
                    anEditingContext.recordObject( result, globalID );
                }
                else // no global id specified
                {
                    if ( result instanceof EOEnterpriseObject )
                    {
                        ((EOEnterpriseObject)result).awakeFromInsertion( anEditingContext );
                    }
                    // register as new object in editing context
                    anEditingContext.insertObject( result );
                }
            }
        }
        catch ( Exception exc )
        {
            // error instantiating
            throw new WotonomyException( exc );
        }
        return result;
    }
  
/*
    public NSFormatter defaultFormatterForKey(
        String key )
    {
        throw new WotonomyException( "Not implemented yet." );
    }
*/
    
    /**
    * Returns the delete rule to be used for the specified 
    * relationship key.
    * This implementation returns DeleteRuleNoAction.
    */ 
    public int deleteRuleForRelationshipKey(
        String relationshipKey )
    {
        return DeleteRuleNoAction;
    }

    /**
    * Returns a human-readable title for the specified key.
    * For example, displayNameForKey( "firstName" ) might 
    * return "First Name".
    * This implementation attempts to construct such a string
    * from the key, uppercasing the first character and 
    * inserting spaces before subsequent uppercase characters.
    */ 
    public String displayNameForKey(
        String key )
    {
        if ( key == null ) return "";
        if ( key.length() == 0 ) return "";
        
        StringBuffer result = new StringBuffer();
        result.append( Character.toUpperCase( key.charAt(0) ) );
        
        char c;
        int len = key.length();
        for ( int i = 1; i < len; i++ )
        {
            c = key.charAt(i);
            if ( Character.isUpperCase( c ) )
            {
                result.append( ' ' );
            }
            result.append( c );
        }
        
        return result.toString();
    }

    /**
    * Returns a human-readable title for the class of objects
    * that this class description represents.  For example,
    * class CustomerObject might return "Customer".
    * This implementation returns the class name.
    */
    public String entityName()
    {
    	String result = theClass.getName();
	    int index = result.lastIndexOf( "." );
	    if ( index == -1 ) return result;
	    return result.substring( index+1 );
    }

    /**
    * Returns the fetch specification associated with this
    * class description that corresponds to the specified name,
    * or null if not found.
    * This implementation returns null.
    */
    public EOFetchSpecification fetchSpecificationNamed(
        String aString )
    {
        return null;
    }

    /**
    * Returns the relationship key by which the object at the 
    * other end of the specified relationship key refers to
    * this object, or null if not found.
    * This implementation returns null.
    */
    public String inverseForRelationshipKey(
        String relationshipKey )
    {
        return null;
    }

    public boolean ownsDestinationObjectsForRelationshipKey(
        String relationshipKey )
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    /**
    * Called when this object has been deleted from the 
    * specified editing context.  The delete rules for this 
    * object's relationships should be executed.
    */
    public void propagateDeleteForObject( 
        Object object, 
        EOEditingContext anEditingContext )
    {
        throw new WotonomyException( "Not implemented yet." );
    }

    /**
    * Returns a List of the "to many" relationships for
    * this class.
    * This implementation returns an empty list.
    */
    public NSArray toManyRelationshipKeys()
    {
        return NSArray.EmptyArray;
    }

    /**
    * Returns a List of the "to one" relationships for
    * this class.
    * This implementation returns an empty list.
    */
    public NSArray toOneRelationshipKeys()
    {
        return NSArray.EmptyArray;
    }

    /**
    * Returns a human-readable description of the specified object
    * that should not exceed 60 characters.
    * This implementation returns anObject.toString().
    */
    public String userPresentableDescriptionForObject(
        Object anObject )
    {
        return anObject.toString();
    }

    /**
    * Verifies that the specified object may be deleted.
    * Throws an exception with a user-readable error message
    * if the delete operation should not be allowed.
    * This implementation does nothing.
    */ 
    public void validateObjectForDelete(
        Object object )
    {
        // does nothing
    }

    /**
    * Verifies that the specified object may be saved.
    * Throws an exception with a user-readable error message
    * if the save operation should not be allowed.
    * This implementation does nothing.
    */ 
    public void validateObjectForSave(
        Object object )
    {
        // does nothing
    }

    /**
    * Validates the specified value for the specified key on this
    * this class.  Returns null if the value is acceptable, or
    * returns an object that should be used in place of the specified
    * object, or throws an exception with a user-readable error message
    * if no acceptable value can be determined.
    * This implementation returns null.
    */ 
    public Object validateValueForKey( Object value, String key)
    {
        return null;
    }
    
    /**
    * Returns the Java Class that this description describes.
    * NOTE: This method is not in the specification.
    */
    public Class getDescribedClass() 
    {
        return theClass;
    }
    
}

/*
 * $Log$
 * Revision 1.3  2006/02/18 22:46:44  cgruber
 * Add Surrogate map from .util into control's internal package, and fix imports.
 *
 * 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.11  2003/08/08 05:50:32  chochos
 * theClass is protected instead of private
 *
 * Revision 1.10  2003/08/08 00:37:44  chochos
 * default constructor is needed by subclasses
 *
 * Revision 1.9  2001/12/20 18:55:46  mpowers
 * Hooks for awakeFromInsertion and awakeFromFetch.
 *
 * Revision 1.8  2001/12/01 23:51:45  mpowers
 * Corrected createWithEditingContext.
 *
 * Revision 1.7  2001/11/25 22:43:38  mpowers
 * Corrected createInstanceWithEditingContext.
 *
 * Revision 1.6  2001/04/29 02:29:31  mpowers
 * Debugging relationship faulting.
 *
 * Revision 1.5  2001/04/28 22:17:51  mpowers
 * Revised PropertyDataSource to be EOClassDescription-aware.
 *
 * Revision 1.4  2001/04/28 14:12:23  mpowers
 * Refactored cloning/copying into KeyValueCodingUtilities.
 *
 * Revision 1.3  2001/04/27 23:37:20  mpowers
 * Now using EOClassDescription in the EODataSource class, as we should.
 *
 * Revision 1.2  2001/04/27 00:27:42  mpowers
 * Partial implementation.
 *
 * Revision 1.1  2001/03/29 03:29:49  mpowers
 * Now using KeyValueCoding and Support instead of Introspector.
 *
 *
 */