lucene-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cutt...@apache.org
Subject cvs commit: jakarta-lucene/src/java/org/apache/lucene/store Directory.java FSDirectory.java InputStream.java OutputStream.java RAMDirectory.java package.html
Date Wed, 31 Jul 2002 17:47:14 GMT
cutting     2002/07/31 10:47:14

  Modified:    .        default.properties
               src/java/org/apache/lucene/store Directory.java
                        FSDirectory.java InputStream.java OutputStream.java
                        RAMDirectory.java package.html
  Log:
  Improved javadoc comments.
  
  Revision  Changes    Path
  1.9       +1 -1      jakarta-lucene/default.properties
  
  Index: default.properties
  ===================================================================
  RCS file: /home/cvs/jakarta-lucene/default.properties,v
  retrieving revision 1.8
  retrieving revision 1.9
  diff -u -r1.8 -r1.9
  --- default.properties	17 Jun 2002 15:34:27 -0000	1.8
  +++ default.properties	31 Jul 2002 17:47:14 -0000	1.9
  @@ -29,7 +29,7 @@
   packages=org.apache.lucene.*
   
   # javadoc link
  -javadoc.link=http://java.sun.com/products/jdk/1.3/docs/api/
  +javadoc.link=http://java.sun.com/j2se/1.4/docs/api/
   
   build.compiler.pedantic=false
   
  
  
  
  1.3       +13 -16    jakarta-lucene/src/java/org/apache/lucene/store/Directory.java
  
  Index: Directory.java
  ===================================================================
  RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/Directory.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- Directory.java	27 Sep 2001 16:27:01 -0000	1.2
  +++ Directory.java	31 Jul 2002 17:47:14 -0000	1.3
  @@ -56,22 +56,19 @@
   
   import java.io.IOException;
   
  -/*
  -  Java's filesystem API is not used directly, but rather through these
  -  classes.  This permits:
  -    . implementation of RAM-based indices, useful for summarization, etc.;
  -    . implementation of an index as a single file.
  -
  -*/
  -
  -/**
  -  A Directory is a flat list of files.  Files may be written once,
  -  when they are created.  Once a file is created it may only be opened for
  -  read, or deleted.  Random access is permitted when reading and writing.
  -
  -    @author Doug Cutting
  -*/
  -
  +/** A Directory is a flat list of files.  Files may be written once, when they
  + * are created.  Once a file is created it may only be opened for read, or
  + * deleted.  Random access is permitted both when reading and writing.
  + *
  + * <p> Java's i/o APIs not used directly, but rather all i/o is
  + * through this API.  This permits things such as: <ul> 
  + * <li> implementation of RAM-based indices;
  + * <li> implementation indices stored in a database, via JDBC;
  + * <li> implementation of an index as a single file;
  + * </ul>
  + *
  + * @author Doug Cutting
  + */
   abstract public class Directory {
     /** Returns an array of strings, one for each file in the directory. */
     abstract public String[] list()
  
  
  
  1.10      +10 -11    jakarta-lucene/src/java/org/apache/lucene/store/FSDirectory.java
  
  Index: FSDirectory.java
  ===================================================================
  RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/FSDirectory.java,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- FSDirectory.java	26 Jun 2002 17:30:11 -0000	1.9
  +++ FSDirectory.java	31 Jul 2002 17:47:14 -0000	1.10
  @@ -63,9 +63,9 @@
   import org.apache.lucene.util.Constants;
   
   /**
  - * Straightforward implementation of Directory as a directory of files.
  - * If the system property 'disableLuceneLocks' has the String value of "true",
  - * lock creation will be disabled.
  + * Straightforward implementation of {@link Directory} as a directory of files.
  + * <p>If the system property 'disableLuceneLocks' has the String value of
  + * "true", lock creation will be disabled.
    *
    * @see Directory
    * @author Doug Cutting
  @@ -217,14 +217,13 @@
       return new FSInputStream(new File(directory, name));
     }
   
  -  /**
  -   * Constructs a {@link Lock} with the specified name.
  -   * If JDK 1.1 is used the lock file is not really made.
  -   * If system property <I>disableLuceneLocks</I> has the value of 'true'
  -   * the lock will not be created.  Assigning this property any other value
  -   * will <B>not</B> prevent creation of locks.
  -   * <BR>
  -   * This is useful for using Lucene on read-only medium, such as CD-ROM.
  +  /** Constructs a {@link Lock} with the specified name.  Locks are implemented
  +   * with {@link File#createNewFile() }.
  +   *
  +   * <p>In JDK 1.1 or if system property <I>disableLuceneLocks</I> is
the
  +   * string "true", locks are disabled.  Assigning this property any other
  +   * string will <B>not</B> prevent creation of lock files.  This is useful
for
  +   * using Lucene on read-only medium, such as CD-ROM.
      *
      * @param name the name of the lock file
      * @return an instance of <code>Lock</code> holding the lock
  
  
  
  1.2       +67 -9     jakarta-lucene/src/java/org/apache/lucene/store/InputStream.java
  
  Index: InputStream.java
  ===================================================================
  RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/InputStream.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- InputStream.java	18 Sep 2001 16:29:59 -0000	1.1
  +++ InputStream.java	31 Jul 2002 17:47:14 -0000	1.2
  @@ -56,12 +56,11 @@
   
   import java.io.IOException;
   
  -/**
  -  Abstract class for input from a file in a Directory.
  -  @author Doug Cutting
  -*/
  -
  -/** A random-access input stream */
  +/** Abstract base class for input from a file in a {@link Directory}.  A
  + * random-access input stream.  Used for all Lucene index input operations.
  + * @see Directory
  + * @see OutputStream
  + */
   abstract public class InputStream implements Cloneable {
     final static int BUFFER_SIZE = OutputStream.BUFFER_SIZE;
   
  @@ -74,13 +73,21 @@
   
     protected long length;			  // set by subclasses
   
  -  /** InputStream-like methods @see java.io.InputStream */
  +  /** Reads and returns a single byte.
  +   * @see OutputStream#writeByte(byte)
  +   */
     public final byte readByte() throws IOException {
       if (bufferPosition >= bufferLength)
         refill();
       return buffer[bufferPosition++];
     }
   
  +  /** Reads a specified number of bytes into an array at the specified offset.
  +   * @param b the array to read bytes into
  +   * @param offset the offset in the array to start storing bytes
  +   * @param len the number of bytes to read
  +   * @see OutputStream#writeBytes(byte[],int)
  +   */
     public final void readBytes(byte[] b, int offset, int len)
          throws IOException {
       if (len < BUFFER_SIZE) {
  @@ -97,11 +104,19 @@
       }
     }
   
  +  /** Reads four bytes and returns an int.
  +   * @see OutputStream#writeInt(int)
  +   */
     public final int readInt() throws IOException {
       return ((readByte() & 0xFF) << 24) | ((readByte() & 0xFF) << 16)
            | ((readByte() & 0xFF) <<  8) |  (readByte() & 0xFF);
     }
   
  +  /** Reads an int stored in variable-length format.  Reads between one and
  +   * five bytes.  Smaller values take fewer bytes.  Negative numbers are not
  +   * supported.
  +   * @see OutputStream#writeVInt(int)
  +   */
     public final int readVInt() throws IOException {
       byte b = readByte();
       int i = b & 0x7F;
  @@ -112,10 +127,16 @@
       return i;
     }
   
  +  /** Reads eight bytes and returns a long.
  +   * @see OutputStream#writeLong(long)
  +   */
     public final long readLong() throws IOException {
       return (((long)readInt()) << 32) | (readInt() & 0xFFFFFFFFL);
     }
   
  +  /** Reads a long stored in variable-length format.  Reads between one and
  +   * nine bytes.  Smaller values take fewer bytes.  Negative numbers are not
  +   * supported. */
     public final long readVLong() throws IOException {
       byte b = readByte();
       long i = b & 0x7F;
  @@ -126,6 +147,9 @@
       return i;
     }
   
  +  /** Reads a string.
  +   * @see OutputStream#writeString(String)
  +   */
     public final String readString() throws IOException {
       int length = readVInt();
       if (chars == null || length > chars.length)
  @@ -134,6 +158,12 @@
       return new String(chars, 0, length);
     }
   
  +  /** Reads UTF-8 encoded characters into an array.
  +   * @param buffer the array to read characters into
  +   * @param start the offset in the array to start storing characters
  +   * @param length the number of characters to read
  +   * @see OutputStream#writeChars(String,int,int)
  +   */
     public final void readChars(char[] buffer, int start, int length)
          throws IOException {
       final int end = start + length;
  @@ -152,7 +182,7 @@
     }
   
   
  -  protected final void refill() throws IOException {
  +  private void refill() throws IOException {
       long start = bufferStart + bufferPosition;
       long end = start + BUFFER_SIZE;
       if (end > length)				  // don't read past EOF
  @@ -169,16 +199,29 @@
       bufferPosition = 0;
     }
   
  +  /** Expert: implements buffer refill.  Reads bytes from the current position
  +   * in the input.
  +   * @param b the array to read bytes into
  +   * @param offset the offset in the array to start storing bytes
  +   * @param length the number of bytes to read
  +   */
     abstract protected void readInternal(byte[] b, int offset, int length)
          throws IOException;
   
  +  /** Closes the stream to futher operations. */
     abstract public void close() throws IOException;
   
  -  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
  +  /** Returns the current position in this file, where the next read will
  +   * occur.
  +   * @see #seek(long)
  +   */
     public final long getFilePointer() {
       return bufferStart + bufferPosition;
     }
   
  +  /** Sets current position in this file, where the next read will occur.
  +   * @see #getFilePointer()
  +   */
     public final void seek(long pos) throws IOException {
       if (pos >= bufferStart && pos < (bufferStart + bufferLength))
         bufferPosition = (int)(pos - bufferStart);  // seek within buffer
  @@ -189,12 +232,27 @@
         seekInternal(pos);
       }
     }
  +
  +  /** Expert: implements seek.  Sets current position in this file, where the
  +   * next {@link #readInternal(byte[],int,int)} will occur.
  +   * @see #readInternal(byte[],int,int)
  +   */
     abstract protected void seekInternal(long pos) throws IOException;
   
  +  /** The number of bytes in the file. */
     public final long length() {
       return length;
     }
   
  +  /** Returns a clone of this stream.
  +   *
  +   * <p>Clones of a stream access the same data, and are positioned at the same
  +   * point as the stream they were cloned from.
  +   *
  +   * <p>Expert: Subclasses must ensure that clones may be positioned at
  +   * different points in the input from each other and from the stream they
  +   * were cloned from.
  +   */
     public Object clone() {
       InputStream clone = null;
       try {
  
  
  
  1.2       +53 -8     jakarta-lucene/src/java/org/apache/lucene/store/OutputStream.java
  
  Index: OutputStream.java
  ===================================================================
  RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/OutputStream.java,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- OutputStream.java	18 Sep 2001 16:29:59 -0000	1.1
  +++ OutputStream.java	31 Jul 2002 17:47:14 -0000	1.2
  @@ -56,12 +56,11 @@
   
   import java.io.IOException;
   
  -/**
  -  Abstract class for output from a file in a Directory.
  -  @author Doug Cutting
  -*/
  -
  -/** A random-access output stream */
  +/** Abstract class for output to a file in a Directory.  A random-access output
  + * stream.  Used for all Lucene index output operations.
  + * @see Directory
  + * @see InputStream
  + */ 
   abstract public class OutputStream {
     final static int BUFFER_SIZE = 1024;
   
  @@ -69,18 +68,28 @@
     private long bufferStart = 0;			  // position in file of buffer
     private int bufferPosition = 0;		  // position in buffer
   
  -  /** OutputStream-like methods @see java.io.InputStream */
  +  /** Writes a single byte.
  +   * @see InputStream#readByte()
  +   */
     public final void writeByte(byte b) throws IOException {
       if (bufferPosition >= BUFFER_SIZE)
         flush();
       buffer[bufferPosition++] = b;
     }
   
  +  /** Writes an array of bytes.
  +   * @param b the bytes to write
  +   * @param length the number of bytes to write
  +   * @see InputStream#readBytes(byte[],int,int)
  +   */
     public final void writeBytes(byte[] b, int length) throws IOException {
       for (int i = 0; i < length; i++)
         writeByte(b[i]);
     }
   
  +  /** Writes an int as four bytes.
  +   * @see InputStream#readInt()
  +   */
     public final void writeInt(int i) throws IOException {
       writeByte((byte)(i >> 24));
       writeByte((byte)(i >> 16));
  @@ -88,6 +97,11 @@
       writeByte((byte) i);
     }
   
  +  /** Writes an int in a variable-length format.  Writes between one and
  +   * five bytes.  Smaller values take fewer bytes.  Negative numbers are not
  +   * supported.
  +   * @see InputStream#readVInt()
  +   */
     public final void writeVInt(int i) throws IOException {
       while ((i & ~0x7F) != 0) {
         writeByte((byte)((i & 0x7f) | 0x80));
  @@ -96,11 +110,19 @@
       writeByte((byte)i);
     }
   
  +  /** Writes a long as eight bytes.
  +   * @see InputStream#readLong()
  +   */
     public final void writeLong(long i) throws IOException {
       writeInt((int) (i >> 32));
       writeInt((int) i);
     }
   
  +  /** Writes an long in a variable-length format.  Writes between one and five
  +   * bytes.  Smaller values take fewer bytes.  Negative numbers are not
  +   * supported.
  +   * @see InputStream#readVLong()
  +   */
     public final void writeVLong(long i) throws IOException {
       while ((i & ~0x7F) != 0) {
         writeByte((byte)((i & 0x7f) | 0x80));
  @@ -109,12 +131,21 @@
       writeByte((byte)i);
     }
   
  +  /** Writes a string.
  +   * @see InputStream#readString()
  +   */
     public final void writeString(String s) throws IOException {
       int length = s.length();
       writeVInt(length);
       writeChars(s, 0, length);
     }
   
  +  /** Writes a sequence of UTF-8 encoded characters from a string.
  +   * @param s the source of the characters
  +   * @param start the first character in the sequence
  +   * @param length the number of characters in the sequence
  +   * @see InputStream#readChars(char[],int,int)
  +   */
     public final void writeChars(String s, int start, int length)
          throws IOException {
       final int end = start + length;
  @@ -133,28 +164,42 @@
       }
     }
   
  +  /** Forces any buffered output to be written. */
     protected final void flush() throws IOException {
       flushBuffer(buffer, bufferPosition);
       bufferStart += bufferPosition;
       bufferPosition = 0;
     }
   
  +  /** Expert: implements buffer write.  Writes bytes at the current position in
  +   * the output.
  +   * @param b the bytes to write
  +   * @param len the number of bytes to write
  +   */
     abstract protected void flushBuffer(byte[] b, int len) throws IOException;
   
  +  /** Closes this stream to further operations. */
     public void close() throws IOException {
       flush();
     }
   
  -  /** RandomAccessFile-like methods @see java.io.RandomAccessFile */
  +  /** Returns the current position in this file, where the next write will
  +   * occur.
  +   * @see #seek(long)
  +   */
     public final long getFilePointer() throws IOException {
       return bufferStart + bufferPosition;
     }
   
  +  /** Sets current position in this file, where the next write will occur.
  +   * @see #getFilePointer()
  +   */
     public void seek(long pos) throws IOException {
       flush();
       bufferStart = pos;
     }
   
  +  /** The number of bytes in the file. */
     abstract public long length() throws IOException;
   
   
  
  
  
  1.4       +2 -0      jakarta-lucene/src/java/org/apache/lucene/store/RAMDirectory.java
  
  Index: RAMDirectory.java
  ===================================================================
  RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/RAMDirectory.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- RAMDirectory.java	31 Oct 2001 00:12:30 -0000	1.3
  +++ RAMDirectory.java	31 Jul 2002 17:47:14 -0000	1.4
  @@ -63,9 +63,11 @@
   import org.apache.lucene.store.InputStream;
   import org.apache.lucene.store.OutputStream;
   
  +/** A memory-resident {@link Directory} implementation. */
   final public class RAMDirectory extends Directory {
     Hashtable files = new Hashtable();
   
  +  /** Constructs an empty {@link Directory}. */
     public RAMDirectory() {
     }
   
  
  
  
  1.2       +1 -1      jakarta-lucene/src/java/org/apache/lucene/store/package.html
  
  Index: package.html
  ===================================================================
  RCS file: /home/cvs/jakarta-lucene/src/java/org/apache/lucene/store/package.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- package.html	18 Sep 2001 16:29:59 -0000	1.1
  +++ package.html	31 Jul 2002 17:47:14 -0000	1.2
  @@ -5,6 +5,6 @@
      <meta name="Author" content="Doug Cutting">
   </head>
   <body>
  -Binary i/o API, for storing index data.
  +Binary i/o API, used for all index data.
   </body>
   </html>
  
  
  

--
To unsubscribe, e-mail:   <mailto:lucene-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:lucene-dev-help@jakarta.apache.org>


Mime
View raw message