/**
 *   GRANITE DATA SERVICES
 *   Copyright (C) 2006-2013 GRANITE DATA SERVICES S.A.S.
 *
 *   This file is part of the Granite Data Services Platform.
 *
 *                               ***
 *
 *   Community License: GPL 3.0
 *
 *   This file is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published
 *   by the Free Software Foundation, either version 3 of the License,
 *   or (at your option) any later version.
 *
 *   This file 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 General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 *                               ***
 *
 *   Available Commercial License: GraniteDS SLA 1.0
 *
 *   This is the appropriate option if you are creating proprietary
 *   applications and you are not prepared to distribute and share the
 *   source code of your application under the GPL v3 license.
 *
 *   Please visit http://www.granitedataservices.com/license for more
 *   details.
 */
package org.granite.client.tide.data.spi;

import java.util.Map;

/**
 * SPI for integrating with different types of data objects (javabeans, javafx bindable beans, ...)
 *
 * @author William DRAI
 */
public interface DataManager {

    /**
     * Is the object an entity (i.e. annotated with {@link org.granite.client.persistence.Entity}) ?
     * @param object object
     * @return true if entity
     */
    public boolean isEntity(Object object);

    /**
     * Return the persistent id of an entity (field annotated with {@link org.granite.client.persistence.Id}) ?
     * @param entity object
     * @return id if field found, error if no id field
     */
    public Object getId(Object entity);

    /**
     * Has the entity an id field ?
     * @param entity object
     * @return true if id field found
     */
    public boolean hasIdProperty(Object entity);

    /**
     * Return the persistent detached state of an entity (private field name __detachedState__)
     * @param entity object
     * @return detached state if field found, error if field not found
     */
    public String getDetachedState(Object entity);

    /**
     * Define the target object as a proxy for the source entity
     * @param target target object
     * @param source source entity
     * @return true if proxy was setup, false if source was not an entity or did not have any detached state
     */
    public boolean defineProxy(Object target, Object source);

    /**
     * Copy the proxy state (fields __initialized__ and __detachedState__) from source to target
     * @param target target object
     * @param source source entity
     */
    public void copyProxyState(Object target, Object source);

    /**
     * Copy the uid field (annotated with {@link org.granite.client.persistence.Uid}) from source to target
     * @param target target object
     * @param source source entity
     */
    public void copyUid(Object target, Object source);

    /**
     * Return the version (field annotated with {@link org.granite.client.persistence.Version}) for an entity
     * @param entity entity
     * @return version or error if no version field found
     */
    public Object getVersion(Object entity);

    /**
     * Has the entity a version field (annotated with {@link org.granite.client.persistence.Version}) ?
     * @param entity object
     * @return true if version field found
     */
    public boolean hasVersionProperty(Object entity);

    /**
     * Name of the version field for the entity
     * @param entity object
     * @return property name or null if not found
     */
    public String getVersionPropertyName(Object entity);

    /**
     * Get the uid field (annotated with {@link org.granite.client.persistence.Uid}) for the entity
     * Note that the data manager implementation is allowed to generate a reasonable uid value from other fields
     * if no uid field is present
     * @param entity object
     * @return uid or error if uid could not be generated
     */
    public String getUid(Object entity);

    /**
     * Return a map of property values for the specified entity instance
     * @param entity object instance
     * @param excludeIdUid true to exclude id and uid fields from the map
     * @param excludeVersion true to exclude version field from the map
     * @param includeReadOnly true to include readonly fields in the map
     * @return a map of values keyed by property names
     */
    public Map<String, Object> getPropertyValues(Object entity, boolean excludeIdUid, boolean excludeVersion, boolean includeReadOnly);

    /**
     * Return a map of property values for the specified entity instance
     * @param entity object instance
     * @param excludeVersion true to exclude version field from the map
     * @param includeReadOnly true to include readonly fields in the map
     * @return a map of values keyed by property names
     */
    public Map<String, Object> getPropertyValues(Object entity, boolean excludeVersion, boolean includeReadOnly);

    /**
     * Return the value of the property for the specified entity instance
     * @param entity object instance
     * @param name property name
     * @return property value
     */
    public Object getPropertyValue(Object entity, String name);

    /**
     * Set the value of the property for the specified entity instance
     * @param entity object instance
     * @param name property name
     * @param value property value
     */
    public void setPropertyValue(Object entity, String name, Object value);

    /**
     * Is the specified property lazy ?
     * A property is considered lazy if it is annotated with {@link org.granite.client.persistence.Lazy} or if the
     * server has returned an initialized value
     * @param entity entity instance
     * @param name property name
     * @return true if property defined as lazy
     */
    public boolean isLazyProperty(Object entity, String name);

    /**
     * Define a property as lazy
     * @param entity entity instance
     * @param name property name
     */
    public void setLazyProperty(Object entity, String name);

    /**
     * Return a unique key for the entity to be used in a local cache
     * @param entity entity instance
     * @return unique key
     */
    public String getCacheKey(Object entity);

    /**
     * Is the entity initialized (field __initialized__ true) ?
     * @param entity entity instance
     * @return true if initialized
     */
    public boolean isInitialized(Object entity);

    /**
     * Is the data manager dirty (any managed entity instance has been modified since last received from server) ?
     * @return true if modified
     */
    public boolean isDirty();

    /**
     * Is the entity instance dirty (modified since last received from server) ?
     * @return true if modified
     */
    public boolean isDirtyEntity(Object entity);

    /**
     * Is the entity graph dirty (any object in the graph of this entity has been modified since last received from server) ?
     * @return true if modified
     */
    public boolean isDeepDirtyEntity(Object entity);


    /**
     * Register a handler that will be notified when any managed entity is modified
     * @param trackingHandler tracking handler
     */
    public void setTrackingHandler(TrackingHandler trackingHandler);

    /**
     * Types of tracked events
     */
    public static enum TrackingType {        
        LIST,
        SET,
        MAP,
        ENTITY_PROPERTY,
        ENTITY_LIST,
        ENTITY_SET,
        ENTITY_MAP
    }

    /**
     * Kinds of changes for collections and maps
     */
    public static enum ChangeKind {
        ADD,
        REMOVE,
        REPLACE,
        UPDATE
    }

    
    /**
     *  Start tracking for the specified object / parent
     *
     *  @param previous previously existing object in the entity manager cache (null if no existing object)
     *  @param parent parent object for collections
     */
    public void startTracking(Object previous, Object parent);
    
    /**
     *  Stop tracking for the specified object / parent
     *
     *  @param previous previously existing object in the entity manager cache (null if no existing object)
     *  @param parent parent object for collections
     */
    public void stopTracking(Object previous, Object parent);

    /**
     *  Reset all currently tracked objects
     */
    public void clear();

    /**
     * Callback interface for objects that need to be notified when modifications are made on managed entities
     */
    public static interface TrackingHandler {

        /**
         * Callback called when a collection is modified
         * @param kind kind of collection change
         * @param target modified collection
         * @param location index/key of the modification
         * @param items array of modified items
         */
        public void collectionChangeHandler(ChangeKind kind, Object target, Integer location, Object[] items);

        /**
         * Callback called when a map is modified
         * @param kind kind of map change
         * @param target modified map
         * @param location key of the modification
         * @param items array of modified entries (each entry is an array [ key, value ])
         */
        public void mapChangeHandler(ChangeKind kind, Object target, Integer location, Object[] items);

        /**
         * Callback when a property of an entity is modified
         * @param target modified entity
         * @param property property name
         * @param oldValue previous value
         * @param newValue new value
         */
        public void entityPropertyChangeHandler(Object target, String property, Object oldValue, Object newValue);

        /**
         * Callback called when a collection owned by an entity (x-to-many association) is modified
         * @param kind kind of collection change
         * @param target modified collection
         * @param location index/key of the modification
         * @param items array of modified items
         */
        public void entityCollectionChangeHandler(ChangeKind kind, Object target, Integer location, Object[] items);

        /**
         * Callback called when a map owned by an entity (x-to-many association) is modified
         * @param kind kind of map change
         * @param target modified map
         * @param location key of the modification
         * @param items array of modified entries (each entry is an array [ key, value ])
         */
        public void entityMapChangeHandler(ChangeKind kind, Object target, Integer location, Object[] items);
    }

    /**
     * Notify listeners that the dirty state of this data manager has changed
     * Called by dirty checking
     * @param oldDirty old value
     * @param dirty new value
     * @see org.granite.client.tide.data.spi.DirtyCheckContext
     */
    public void notifyDirtyChange(boolean oldDirty, boolean dirty);

    /**
     * Notify listeners that the dirty state of the specified has changed
     * @param entity entity instance
     * @param oldDirtyEntity old value
     * @param newDirtyEntity new value
     * @see org.granite.client.tide.data.spi.DirtyCheckContext
     */
    public void notifyEntityDirtyChange(Object entity, boolean oldDirtyEntity, boolean newDirtyEntity);

}