[Jackrabbit Wiki] Update of "PersistenceManagerFAQ" by ThomasMueller

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jackrabbit Wiki" for change notification.

The "PersistenceManagerFAQ" page has been changed by ThomasMueller.
http://wiki.apache.org/jackrabbit/PersistenceManagerFAQ?action=diff&rev1=33&rev2=34

--------------------------------------------------

- = Persistence Manager (PM) FAQ =
+ == Persistence Manager ==
  
+ <<TableOfContents>>
+ 
+ == Overview ==
+ 
- == What is a Persistence Manager (PM)? ==
+ === What Is a Persistence Manager (PM)? ===
  The PM is an *internal* Jackrabbit component that handles the persistent storage of content nodes and properties. Property values are also stored in the persistence manager, with the exception of large binary values (those are usually kept in the DataStore).
  
  Each workspace of a Jackrabbit content repository uses a separate persistence manager to store the content in that workspace. Also the Jackrabbit version handler uses a separate persistence manager. 
@@ -26, +30 @@

  The PM sits at the very bottom layer in jackrabbits system architecture. 
  Reliability, integrity and performance of the PM are *crucial* to the overall stability & performance of the repository. If e.g. the data that a PM is based upon is allowed to change through external means the integrity of the repository would be at risk (think of referential integrity / node references e.g.).
  
- ==== Which Persistence Manager is the fastest? ====
+ === Which Persistence Manager Is the Fastest? ===
  The bundle persistence managers are usually the fastest. Bundle persistence managers store each node together with all the properties as one unit. Large binary properties are stored to the BLOBStore by default (or DataStore if configured). Setting the minimum blob size for bundle persistence managers very high decreases the performance.
  
  Storing the data in the file system does not require a database. Depending on the file system and database, database persistence managers are sometimes slower and sometimes faster than the Bundle``Fs``Persistence``Manager. When using a database, please note that embedded Java databases do not have network overhead.
  
- ==== Consistency / Atomicy ====
+ === Consistency / Atomicy ===
  
  The database persistence managers are atomic if the database is atomic.
  
  The current file based persistence managers are not always atomic. They do support transactions in Jackrabbit, the exception is after a crash: When the process is stopped while a transaction is being written to disk (power failure, process killed, Runtime.halt() called, VM crash), some data of a transaction may be committed and some not. Theoretically, some nodes may be corrupt (depending how and when the system crashed). The algorithms used are minimizing this risk, for example the parent node is written last so in most cases there is no problem even after a crash. 
  
- ==== What's the PM responsibility? ====
+ === What's the PM Responsibility? ===
  The PM interface was never intended as being a general SPI that you could implement in order to integrate external datasources with proprietary formats (e.g. a customers database). the reason why we abstracted the PM interface was to leave room for future performance optimizations that  would not affect the rest of the implementation (e.g. by storing the raw data in a b-tree based database instead of individual file).
  
- ==== How smart should a PM be? ====
+ === How Smart Should a PM Be? ===
  A PM should not be 'intelligent'. It should not 'interpret' the data. The only thing a PM should care about is to efficiently, consistently and reliably store and read the data encapsulated in the passed nodeState & propertyState objects. Though it might be feasible to write a custom persistence manager to represent existing legacy data in a level-1 (read-only) repository, I don't think the same is possible for a level-2 repository.  At a minimum, it certainly would not be recommended.
  
- ==== File System (FS) ====
+ === File System (FS) ===
  
  Jackrabbit uses the org.apache.jackrabbit.core.fs.FileSystem interface as a file system abstraction. Although this interface does not cover all direct file system use of Jackrabbit, it still allows for flexibility in selecting where and how to store various parts of the repository. For example, because it is possible with Jackrabbit to configure separate file systems for different system components (e.g., global repository state, workspaces, search indexes, versioning, etc), it might make sense to store the search indexes on a fast disk and the archived node versions on a slower disk. 
  
- ==== What combination of FS and PM is the best choice? ====
+ === What Combination of FS and PM is the Best Choice? ===
  It depends on your priorities. If you want to store your data in a RDBMS, use Bundle``Db``Persistence``Manager in conjunction with either a Local``File``System or Db``File``System. If you want to store your data in an more readily accessible format (just in case ;), you might want to try an XML``Persistence``Manager paired with a Local``File``System.
  
  == Available Implementations ==
  
- ==== Bundle Database PM ====
+ === Bundle Database PM ===
   * Status: mature (the default persistence manager)
   * Depending on the database, one of the following:
     * org.apache.jackrabbit.core.persistence.bundle.Derby``Persistence``Manager (Apache Derby; Java)
@@ -69, +73 @@

   * The tables are automatically created. To create them manually, see [[ManuallyCreatingDatabaseTables]].
   * [[http://jackrabbit.apache.org/api/1.5/org/apache/jackrabbit/core/persistence/bundle/BundleDbPersistenceManager.html|BundleDbPersistenceManager]]
  
- ==== Bundle File-System PM ====
+ === Bundle File-System PM ===
   * Status: mature
   * If the JVM process is killed the repository might turn inconsistent
   * Not meant to be used in production environments (except for read-only uses)
@@ -77, +81 @@

   * Very fast if used with DataStore or BLOBStore
   * [[http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/persistence/bundle/BundleFsPersistenceManager.html|BundleFsPersistenceManager]]
  
- ==== In-Memory PM ====
+ === In-Memory PM ===
   * Status: mature
   * All data is lost as soon as the repository is closed
   * org.apache.jackrabbit.core.persistence.mem.In``Mem``Persistence``Manager
@@ -87, +91 @@

   * Very fast
   * [[http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/persistence/mem/InMemPersistenceManager.html|InMemPersistenceManager]]
  
- ==== Simple Database PM ====
+ === Simple Database PM ===
   * Status: mature
   * Subclasses of org.apache.jackrabbit.core.persistence.db.Simple``Db``Persistence``Manager
   * JDBC based; zero-deployment: schema is automatically created
@@ -95, +99 @@

   * Fast
   * [[http://jackrabbit.apache.org/api/1.4/org/apache/jackrabbit/core/persistence/db/SimpleDbPersistenceManager.html|SimpleDbPersistenceManager]]
  
- ==== ObjectPersistenceManager ====
+ === ObjectPersistenceManager ===
   * Status: obsolete, mature
   * If the JVM process is killed the repository might turn inconsistent
   * Not meant to be used in production environments 
   * Persists data in an abstract File``System using a simple binary serialization format
  
- ==== XMLPersistenceManager ====
+ === XMLPersistenceManager ===
   * Status: obsolete, mature
   * If the JVM process is killed the repository might turn inconsistent
   * Persists data in an abstract File``System using XML serialization format
  
- ==== ORMPersistenceManager ====
+ === ORMPersistenceManager ===
   * Status: obsolete, experimental & unfinished, still being maintained?
   * Referential integrity is possible, but not implemented
   * Not so easy to configure.
  
- ==== LocalFileSystem: ====
+ === LocalFileSystem: ===
   * Status: mature
   * Slow on window boxes
  
- ==== MemoryFileSystem: ====
+ === MemoryFileSystem: ===
   * Status: mature
   * All data is lost as soon as the repository is closed
   * For testing and small (read-only) workspaces 
   * Keeps all content in memory
   * Very fast
  
- ==== DbFileSystem: ====
+ === DbFileSystem: ===
   * Status: mature
   * Atomic
   * Meant to be used in combination with a Database Persistence Manager as repository & workspace file system