Merge branch 'develop' of https://github.com/orientechnologies/orientdb into develop

lvca · lvca · commit e60de1e9e1f8 · 2014-04-30T15:41:43.000+02:00
diff --git a/core/src/main/java/com/orientechnologies/orient/core/storage/impl/local/paginated/base/ODurableComponent.java b/core/src/main/java/com/orientechnologies/orient/core/storage/impl/local/paginated/base/ODurableComponent.java
@@ -24,6 +24,35 @@
 import com.orientechnologies.orient.core.storage.impl.local.paginated.wal.*;
 
 /**
+ * Base class for all durable data structures, that is data structures state of which can be consistently restored after system
+ * crash but results of last operations in small interval before crash may be lost.
+ * 
+ * This class contains methods which are used to support such concepts as:
+ * <ol>
+ * <li>"atomic operation" - set of operations which should be either applied together or not. It includes not only changes on
+ * current data structure but on all durable data structures which are used by current one during implementation of specific
+ * operation.</li>
+ * <li>write ahead log - log of all changes which were done with page content after loading it from cache.</li>
+ * </ol>
+ * 
+ * 
+ * To support of "atomic operation" concept following should be done:
+ * <ol>
+ * <li>Call {@link #startAtomicOperation()} method.</li>
+ * <li>If changes should be isolated till operation completes call also {@link #lockTillAtomicOperationCompletes()} which will apply
+ * exclusive lock on existing data structure till atomic operation completes. This lock is not replacement of data structure locking
+ * system it is used to serialize access to set of components which participate in single atomic operation. It is kind of rudiment
+ * lock manager which is used to isolate access to units which participate in single transaction and which is going to be created to
+ * provide efficient multi core scalability feature. It is recommended to always call it just after start of atomic operation but
+ * always remember it is not replacement of thread safety mechanics for current data structure it is a mean to provide isolation
+ * between atomic operations.</li>
+ * <li>Log all page changes in WAL by calling of {@link #logPageChanges(ODurablePage, long, long, boolean)}</li>
+ * <li>Call {@link #endAtomicOperation(boolean)} method when atomic operation completes, passed in parameter should be
+ * <code>false</code> if atomic operation completes with success and <code>true</code> if there were some exceptions and it is
+ * needed to rollback given operation.</li>
+ * </ol>
+ * 
+ * 
  * @author Andrey Lomakin
  * @since 8/27/13
  */
diff --git a/core/src/main/java/com/orientechnologies/orient/core/storage/impl/local/paginated/base/ODurablePage.java b/core/src/main/java/com/orientechnologies/orient/core/storage/impl/local/paginated/base/ODurablePage.java
@@ -27,6 +27,26 @@
 import com.orientechnologies.orient.core.storage.impl.local.paginated.wal.OPageChanges;
 
 /**
+ * Base page class for all durable data structures, that is data structures state of which can be consistently restored after system
+ * crash but results of last operations in small interval before crash may be lost.
+ * 
+ * This page has several booked memory areas with following offsets at the beginning:
+ * <ol>
+ * <li>from 0 to 7 - Magic number</li>
+ * <li>from 8 to 11 - crc32 of all page content, which is calculated by cache system just before save</li>
+ * <li>from 12 to 23 - LSN of last operation which was stored for given page</li>
+ * </ol>
+ * 
+ * Developer which will extend this class should use all page memory starting from {@link #NEXT_FREE_POSITION} offset.
+ * 
+ * To make page changes durable method {@link ODurableComponent#logPageChanges(ODurablePage, long, long, boolean)} should be called
+ * just before release of page
+ * {@link com.orientechnologies.orient.core.index.hashindex.local.cache.ODiskCache#release(com.orientechnologies.orient.core.index.hashindex.local.cache.OCacheEntry)}
+ * back to the cache.
+ * 
+ * All data structures which use this kind of pages should be derived from
+ * {@link com.orientechnologies.orient.core.storage.impl.local.paginated.base.ODurableComponent} class.
+ * 
  * @author Andrey Lomakin
  * @since 16.08.13
  */
