svn commit: r1332632 - /lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/CompoundFileDirectory.java

[rm...@apache.org]

Author: rmuir
Date: Tue May  1 12:48:31 2012
New Revision: 1332632

URL: http://svn.apache.org/viewvc?rev=1332632&view=rev
Log:
LUCENE-2946: doc 4.0 compound file format

Modified:
    lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/CompoundFileDirectory.java

Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/CompoundFileDirectory.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/CompoundFileDirectory.java?rev=1332632&r1=1332631&r2=1332632&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/CompoundFileDirectory.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/store/CompoundFileDirectory.java Tue May  1 12:48:31 2012
@@ -17,8 +17,11 @@ package org.apache.lucene.store;
  * limitations under the License.
  */
 
+import org.apache.lucene.codecs.Codec; // javadocs
+import org.apache.lucene.codecs.LiveDocsFormat; // javadocs
 import org.apache.lucene.index.CorruptIndexException;
 import org.apache.lucene.index.IndexFileNames;
+import org.apache.lucene.store.DataOutput; // javadocs
 import org.apache.lucene.util.IOUtils;
 
 import java.util.Collection;
@@ -32,6 +35,32 @@ import java.io.IOException;
  * Class for accessing a compound stream.
  * This class implements a directory, but is limited to only read operations.
  * Directory methods that would normally modify data throw an exception.
+ * <p>
+ * All files belonging to a segment have the same name with varying extensions.
+ * The extensions correspond to the different file formats used by the {@link Codec}. 
+ * When using the Compound File format these files are collapsed into a 
+ * single <tt>.cfs</tt> file (except for the {@link LiveDocsFormat}, with a 
+ * corresponding <tt>.cfe</tt> file indexing its sub-files.
+ * <p>
+ * Files:
+ * <ul>
+ *    <li><tt>.cfs</tt>: An optional "virtual" file consisting of all the other 
+ *    index files for systems that frequently run out of file handles.
+ *    <li><tt>.cfe</tt>: The "virtual" compound file's entry table holding all 
+ *    entries in the corresponding .cfs file.
+ * </ul>
+ * <p>Description:</p>
+ * <ul>
+ *   <li>Compound (.cfs) --&gt; FileData <sup>FileCount</sup></li>
+ *   <li>Compound Entry Table (.cfe) --&gt; Version, FileCount, &lt;FileName,
+ *       DataOffset, DataLength&gt; <sup>FileCount</sup></li>
+ *   <li>Version --&gt; {@link DataOutput#writeInt Int32}</li>
+ *   <li>FileCount --&gt; {@link DataOutput#writeVInt VInt}</li>
+ *   <li>DataOffset,DataLength --&gt; {@link DataOutput#writeLong UInt64}</li>
+ *   <li>FileName --&gt; {@link DataOutput#writeString String}</li>
+ *   <li>FileData --&gt; raw file data</li>
+ * </ul>
+ * 
  * @lucene.experimental
  */
 public final class CompoundFileDirectory extends Directory {