commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ozeigerm...@apache.org
Subject cvs commit: jakarta-commons-sandbox/transaction/xdocs/file index.xml
Date Mon, 01 Nov 2004 20:01:07 GMT
ozeigermann    2004/11/01 12:01:07

  Modified:    transaction/xdocs/file index.xml
  Log:
  Completed documentation
  
  Revision  Changes    Path
  1.2       +60 -1     jakarta-commons-sandbox/transaction/xdocs/file/index.xml
  
  Index: index.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons-sandbox/transaction/xdocs/file/index.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- index.xml	1 Nov 2004 18:25:51 -0000	1.1
  +++ index.xml	1 Nov 2004 20:01:07 -0000	1.2
  @@ -10,7 +10,66 @@
    <body>
   
   <section name="Transactional file access">
  - <p></p> 
  + <p>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
  + you 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.</p> 
  +
  +<p>The <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/package-summary.html">transactional
  +file</a> package provides you with code that allows you to have atomic
  +read and write operations on any file system. The <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html">file
  +resource manager</a> offers you the possibility to isolate a number of
  +operations on a set of files in a transaction. Using the <a
  +href="../locks/index.html">locks package</a> 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 <em>not</em> be
  +monitored by the manager.</p>
  +
  +<p>When you <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html#startTransaction(java.lang.Object)">start</a>
  +a transaction you need to provide an indentifier to later refer to
  +this newly started transaction. You can also let an identifier be <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html#generatedUniqueTxId()">generated</a>
  +for you. Calls to e.g. <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html#readResource(java.lang.Object,%20java.lang.Object)">read</a>,
  +<a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html#createResource(java.lang.Object,%20java.lang.Object)">create</a>
  +or <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html#writeResource(java.lang.Object,%20java.lang.Object)">write
  +to</a> will need the identifier to know which transaction they belong to.</p>

  +
  +<p>Finally when you want to
  +commit the transaction call <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html#commitTransaction(java.lang.Object)">commit</a>
  +or <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileResourceManager.html#rollbackTransaction(java.lang.Object)">rollback</a>
  +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.
  +</p>
  +
  +<p>A fail safe <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileSequence.html">file
  +sequence</a> 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 <a
  +href="http://jakarta.apache.org/commons/sandbox/transaction/apidocs/org/apache/commons/transaction/file/FileSequence.html#nextSequenceValueBottom(java.lang.String,%20long)">next</a>
  +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. 
  +</p>
   </section>
   
   </body>
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message