Sometimes it may be desirable to save a single file or even a number of related files to the file system atomically. This means if you write something and an error occurs or for any reason you change your mind and rather want to cancel what you did. Consider your application fails in the middle of overwriting important data which neither gives you the old state nor the new one, but rather a corrupted one. Or only part of your data has been written leaving you with an inconsistent state.
The transactional file package provides you with code that allows you to have atomic read and write operations on any file system. The file resource manager offers you the possibility to isolate a number of operations on a set of files in a transaction. Using the locks package it is able to offer you full ACID transactions including serializability. Of course to make this work all access to the managed files must be done by this manager. Direct access to the file system can not be monitored by the manager.
When you start a transaction you need to provide an indentifier to later refer to this newly started transaction. You can also let an identifier be generated for you. Calls to e.g. read, create or write to will need the identifier to know which transaction they belong to.
Finally when you want to commit the transaction call commit or rollback to undo all changes. The transactionality is achieved by first writing to temporary files and upon commit moving or copying them to the primary location. Locks and a delicate commit mechanism will assure that no data corruption occurs.
A fail safe file sequence is the second main part of the file package. Just like sequences known from Oracle or other relational database systems it provides you with a unique ids. Each call to the next method will return a new unique long number and persists the current value of the sequence to disk. This means when you shut down your system and restart it you will still get no double numbers, but the sequence will continue. Additionally, this sequence implementation is fail safe which means when an error occurs while saving the value of the sequence to disk you still are guaranteed not to get any double values. The file containing the value is guaranteed not to be corrupted as well.