----------------------------------------------------------------------------------------------------------------------------
The difference between FileStorageFacade and a FileStorageHandler
While incrementally working on FileStorage I found out that its often inpractical to open and close filestreams yourself (remember we have both an index file, and a data file) and you simple only want to perform one specific operation on a FileStorage like add a file to it and continue focusing on your own business logic rather than having to worry about whether you left the FileStorage in the right state after using it. Therefore since version 1.2.0 there's a FileStorageFacade which will be perfect for most users. The Facade is like a gateway that deals with the complex things, or plumbing, that you don't want to be bothered with. In this case the Facade only has static methods and functions, that itself is responsible for instantiating a FileStorageHandler, opening streams and closing them afterwards.
The FileStorageHandler encapsulates the more more complex logic that requires you to really know what you are doing, otherwise chances are pretty big you might write code that assumes a certain stream is open, but it has just been closed by another function and therefore resulting in an Exception, etc.etc. In some cases however, you might want to do the more advanced things with the FileStorage, and thus need access to the FileStorageHandler. We marked the constructor of the FileStorageHandler private on purpose, to encourage the end users to use the Facade.
/// <summary>
/// Private constructor; its highly recommended to use the static methods and functions of the
/// Facade rather than to access the functionality of the handler yourself.
///
/// If you do want to access the FileStorageHandler yourself, use the static method
/// CreateFileStorageHandlerInstance that will return the instance for you. Please be aware of
/// the handling and de-allocation of the file streams yourself!
/// </summary>
private FileStorageHandler(string containerName)
{
...
}
If you do want to get the instance of the FileStorageHandler yourself, use the static method CreateFileStorageHandlerInstance, like so
/// <summary>
/// Returns an instance of the FileStorageHandler; use the static methods and functions of the
/// Facade to access the 'core' functionality of the handler. Only use the instance if
/// you want to control the opening and closing of index and data file streams yourself (for
/// performance improvements).
///
/// Its is recommended to use the static methods and functions to prevent leaving file streams
/// open.
/// </summary>
public static FileStorageHandler CreateFileStorageHandlerInstance(string containerName)
{
...
}
----------------------------------------------------------------------------------------------------------------------------