//---------------------------------------------------------------------
// <copyright file="IUpdatable.cs" company="Microsoft">
//      Copyright (c) Microsoft Corporation.  All rights reserved.
// </copyright>
// <summary>
//      Provides the interface that needs to be implemented for 
//      supporting updating of resources
// </summary>
//
// @owner  pratikp
//---------------------------------------------------------------------
 
namespace System.Data.Services
{
    using System.Linq;
 
    /// <summary>
    /// This interface declares the methods required for supporting
    /// update of resources
    /// </summary>
    public interface IUpdatable
    {
        /// <summary>
        /// Creates the resource of the given type and belonging to the given container
        /// </summary>
        /// <param name="containerName">container name to which the resource needs to be added</param>
        /// <param name="fullTypeName">full type name i.e. Namespace qualified type name of the resource</param>
        /// <returns>object representing a resource of given type and belonging to the given container</returns>
        object CreateResource(string containerName, string fullTypeName);
 
        /// <summary>
        /// Gets the resource of the given type that the query points to
        /// </summary>
        /// <param name="query">query pointing to a particular resource</param>
        /// <param name="fullTypeName">full type name i.e. Namespace qualified type name of the resource</param>
        /// <returns>object representing a resource of given type and as referenced by the query</returns>
        object GetResource(IQueryable query, string fullTypeName);
 
        /// <summary>
        /// Resets the value of the given resource to its default value
        /// </summary>
        /// <param name="resource">resource whose value needs to be reset</param>
        /// <returns>same resource with its value reset</returns>
        object ResetResource(object resource);
 
        /// <summary>
        /// Sets the value of the given property on the target object
        /// </summary>
        /// <param name="targetResource">target object which defines the property</param>
        /// <param name="propertyName">name of the property whose value needs to be updated</param>
        /// <param name="propertyValue">value of the property</param>
        void SetValue(object targetResource, string propertyName, object propertyValue);
 
        /// <summary>
        /// Gets the value of the given property on the target object
        /// </summary>
        /// <param name="targetResource">target object which defines the property</param>
        /// <param name="propertyName">name of the property whose value needs to be updated</param>
        /// <returns>the value of the property for the given target resource</returns>
        object GetValue(object targetResource, string propertyName);
 
        /// <summary>
        /// Sets the value of the given reference property on the target object
        /// </summary>
        /// <param name="targetResource">target object which defines the property</param>
        /// <param name="propertyName">name of the property whose value needs to be updated</param>
        /// <param name="propertyValue">value of the property</param>
        void SetReference(object targetResource, string propertyName, object propertyValue);
 
        /// <summary>
        /// Adds the given value to the collection
        /// </summary>
        /// <param name="targetResource">target object which defines the property</param>
        /// <param name="propertyName">name of the property whose value needs to be updated</param>
        /// <param name="resourceToBeAdded">value of the property which needs to be added</param>
        void AddReferenceToCollection(object targetResource, string propertyName, object resourceToBeAdded);
 
        /// <summary>
        /// Removes the given value from the collection
        /// </summary>
        /// <param name="targetResource">target object which defines the property</param>
        /// <param name="propertyName">name of the property whose value needs to be updated</param>
        /// <param name="resourceToBeRemoved">value of the property which needs to be removed</param>
        void RemoveReferenceFromCollection(object targetResource, string propertyName, object resourceToBeRemoved);
 
        /// <summary>
        /// Delete the given resource
        /// </summary>
        /// <param name="targetResource">resource that needs to be deleted</param>
        void DeleteResource(object targetResource);
 
        /// <summary>
        /// Saves all the pending changes made till now
        /// </summary>
        void SaveChanges();
 
        /// <summary>
        /// Returns the actual instance of the resource represented by the given resource object
        /// </summary>
        /// <param name="resource">object representing the resource whose instance needs to be fetched</param>
        /// <returns>The actual instance of the resource represented by the given resource object</returns>
        object ResolveResource(object resource);
 
        /// <summary>
        /// Revert all the pending changes.
        /// </summary>
        void ClearChanges();
    }
}