Zeta Enterprise Library

namespace Zeta.EnterpriseLibrary.Tools.Storage
{
	#region Using directives.
	// ------------------------------------------------------------------

	using System.Runtime.InteropServices;

	// ------------------------------------------------------------------
	#endregion

	/////////////////////////////////////////////////////////////////////////

	/// <summary>
	/// Interface that is implemented by a class that can persist
	/// name-value pairs.
	/// </summary>
	[ComVisible( false )]
	public interface IPersistentPairStorage
	{
		#region Interface members.
		// ------------------------------------------------------------------

		/// <summary>
		/// Persist a value.
		/// </summary>
		/// <param name="name">The name of the value to persist.</param>
		/// <param name="value">The value to persist.</param>
		void PersistValue(
			string name,
			object value );

		/// <summary>
		/// Retrieve a value.
		/// </summary>
		/// <param name="name">The name of the value to retrieve.</param>
		/// <returns>Returns the retrieved value or NULL if not available.</returns>
		object RetrieveValue(
			string name );

		/// <summary>
		/// Retrieve a value.
		/// </summary>
		/// <param name="name">The name of the value to retrieve.</param>
		/// <param name="fallBackValue">The value to return when the retrieved
		/// value is not available.</param>
		/// <returns>Returns the retrieved value or '<paramref name="fallBackValue"/>' 
		/// if not available.</returns>
		object RetrieveValue(
			string name,
			object fallBackValue );

		/// <summary>
		/// Deletes the value. Does NOT throw if not exists.
		/// </summary>
		/// <param name="name">The name.</param>
		void DeleteValue(
			string name );

		/// <summary>
		/// Flushes this instance. Stores the cached in-memory values to
		/// the persistent medium, e.g. registry or disk.
		/// </summary>
		void Flush();

		// ------------------------------------------------------------------
		#endregion
	}

	/////////////////////////////////////////////////////////////////////////
}