Lucene-2.2.0 源代码阅读学习(13)

Directory抽象类比较常用的具体实现子类应该是FSDirectory类和RAMDirectory类。FSDirectory类是与文件系统的目录相关的，而RAMDirectory类是与内存相关的，即是指内存中的一个临时非永久的区域。

FSDirectory类源代码定义如下：

package org.apache.lucene.store;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.RandomAccessFile;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Hashtable;

import org.apache.lucene.index.IndexFileNameFilter;

import org.apache.lucene.index.IndexWriter;

public class FSDirectory extends Directory {
   
// DIRECTORIES需要进行同步，用于存放指定键值对<File,FSDirectory>
private static final Hashtable DIRECTORIES = new Hashtable();

private static boolean disableLocks = false;

/**
   * 设置锁文件是否可以使用
   * They should only be disabled if the index
   * is on a read-only medium like a CD-ROM.
   */
public static void setDisableLocks(boolean doDisableLocks) {
    FSDirectory.disableLocks = doDisableLocks;
}

// 获取锁文件是否可以使用，返回true表示不可以使用
public static boolean getDisableLocks() {
    return FSDirectory.disableLocks;
}

// 锁目录，该属性已经废弃
public static final String LOCK_DIR = System.getProperty("org.apache.lucene.lockDir",
                                                           System.getProperty("java.io.tmpdir"));

// 定义一个静态内部类，该类是基于文件系统的
private static Class IMPL;
static {
    try {
      String name =
        System.getProperty("org.apache.lucene.FSDirectory.class",
                           FSDirectory.class.getName());
      IMPL = Class.forName(name);
    } catch (ClassNotFoundException e) {
      throw new RuntimeException("cannot load FSDirectory class: " + e.toString(), e);
    } catch (SecurityException se) {
      try {
        IMPL = Class.forName(FSDirectory.class.getName());
      } catch (ClassNotFoundException e) {
        throw new RuntimeException("cannot load default FSDirectory class: " + e.toString(), e);
      }
    }
}

private static MessageDigest DIGESTER;

static {
    try {
      DIGESTER = MessageDigest.getInstance("MD5");
    } catch (NoSuchAlgorithmException e) {
        throw new RuntimeException(e.toString(), e);
    }
}

/** A buffer optionally used in renameTo method */
private byte[] buffer = null;

// 静态方法，根据指定的路径path，返回该路径的一个FSDirectiry实例
public static FSDirectory getDirectory(String path)
      throws IOException {
    return getDirectory(new File(path), null);
}

// 静态方法，根据指定的路径path以及锁工厂LockFactory参数，返回该路径的一个FSDirectiry实例
public static FSDirectory getDirectory(String path, LockFactory lockFactory)
      throws IOException {
    return getDirectory(new File(path), lockFactory);
}

// 静态方法，根据指定的File对象，返回该路径的一个FSDirectiry实例

public static FSDirectory getDirectory(File file)
    throws IOException {
    return getDirectory(file, null);
}

  // 静态方法，根据指定File对象以及锁工厂LockFactory参数，返回该路径的一个FSDirectiry实例

// 该方法是获取FSDirectiry实例的核心方法，其他重载的该方法都是经过转换，调用该方法实现的
public static FSDirectory getDirectory(File file, LockFactory lockFactory)
    throws IOException
{
    file = new File(file.getCanonicalPath());

    if (file.exists() && !file.isDirectory())    // 如果file存在并且不是一个目录文件，抛出异常
      throw new IOException(file + " not a directory");

    if (!file.exists())    // 如果file不存在
      if (!file.mkdirs())    //   如果创建由file指定的路径名所指定的目录失败，则很可能已经存在，抛出异常
        throw new IOException("Cannot create directory: " + file);

    FSDirectory dir;
    synchronized (DIRECTORIES) {
      dir = (FSDirectory)DIRECTORIES.get(file);
      if (dir == null) {
        try {
          dir = (FSDirectory)IMPL.newInstance();    // 调用静态内部类IMPL获取一个与文件系统目录有关的Directory类，并加载该类
        } catch (Exception e) {
          throw new RuntimeException("cannot load FSDirectory class: " + e.toString(), e);    // 加载失败
        }
        dir.init(file, lockFactory);    // 根据指定的file和lockFactory，调用该类Directory的init方法，进行FSDirectory的初始化初始化工作

        DIRECTORIES.put(file, dir);
      } else {
       // 如果该目录dir管理所用的锁工厂实例为空，或者不是同一个锁工厂实例，抛出异常
        if (lockFactory != null && lockFactory != dir.getLockFactory()) {
          throw new IOException("Directory was previously created with a different LockFactory instance; please pass null as the lockFactory instance and use setLockFactory to change it");
        }
      }
    }
    synchronized (dir) {
      dir.refCount++;    //   用于记录该目录dir被引用的计数增加1
    }
    return dir;
}

//   获取FSDirectory实例，该方法已经废弃
public static FSDirectory getDirectory(String path, boolean create)
      throws IOException {
    return getDirectory(new File(path), create);
}

  //   获取FSDirectory实例，该方法已经废弃
public static FSDirectory getDirectory(File file, boolean create)
    throws IOException
{
    FSDirectory dir = getDirectory(file, null);

    // This is now deprecated (creation should only be done
    // by IndexWriter):
    if (create) {
      dir.create();
    }

    return dir;
}

private void create() throws IOException {
    if (directory.exists()) {    // File directory是FSDirectory类的一个成员
      String[] files = directory.list(IndexFileNameFilter.getFilter());            // 获取经过IndexFileNameFilter过滤后的该目录文件directory下的文件列表
      if (files == null)    // 如果获取的文件列表为空
        throw new IOException("cannot read directory " + directory.getAbsolutePath() + ": list() returned null");
      for (int i = 0; i < files.length; i++) {    //   删除返回的文件列表中的文件
        File file = new File(directory, files[i]);
        if (!file.delete())
          throw new IOException("Cannot delete " + file);    // 删除异常
      }
    }
    lockFactory.clearLock(IndexWriter.WRITE_LOCK_NAME);    // 删除操作完成后，从锁工厂中清除锁，即释放锁
}

private File directory = null;    // File directory是FSDirectory类的一个成员
private int refCount;    //   用于记录该目录dir被引用的计数增加1

protected FSDirectory() {};                     // permit subclassing

private void init(File path, LockFactory lockFactory) throws IOException {

    // 根据指定的file和lockFactory，调用该类Directory的init方法，进行FSDirectory的初始化初始化工作

    directory = path;

    boolean doClearLockID = false;

    if (lockFactory == null) {    // 锁工厂实例为null

      if (disableLocks) {    // 如果锁不可以使用
         lockFactory = NoLockFactory.getNoLockFactory();    // 调用NoLockFactory类，获取NoLockFactory实例，为当前的锁工厂实例。其实NoLockFactory是一个单态(singleton)模式的工厂类，应用中只能有一个锁实例，不需要进行同步
      } else {    // 如果锁可以使用，获取锁工厂类名称的字符串描述
        String lockClassName = System.getProperty("org.apache.lucene.store.FSDirectoryLockFactoryClass");

        if (lockClassName != null && !lockClassName.equals("")) {    // 如果获取的锁工厂类名称的字符串描述不为null，而且者不为空
          Class c;

          try {
            c = Class.forName(lockClassName);    // 加载该锁工厂类
          } catch (ClassNotFoundException e) {
            throw new IOException("unable to find LockClass " + lockClassName);
          }

          try {
            lockFactory = (LockFactory) c.newInstance();    //   获取一个锁工厂的实例        
          } catch (IllegalAccessException e) {
            throw new IOException("IllegalAccessException when instantiating LockClass " + lockClassName);
          } catch (InstantiationException e) {
            throw new IOException("InstantiationException when instantiating LockClass " + lockClassName);
          } catch (ClassCastException e) {
            throw new IOException("unable to cast LockClass " + lockClassName + " instance to a LockFactory");
          }

          // 根据获取的锁工厂实例的类型来设置对文件File path加锁的方式

          if (lockFactory instanceof NativeFSLockFactory) {    
            ((NativeFSLockFactory) lockFactory).setLockDir(path);
          } else if (lockFactory instanceof SimpleFSLockFactory) {
            ((SimpleFSLockFactory) lockFactory).setLockDir(path);
          }
        } else {
          // 没有其他的锁工厂类可用，则使用默认的锁工厂类创建一个锁工厂实例
          lockFactory = new SimpleFSLockFactory(path);
          doClearLockID = true;
        }
      }
    }

    setLockFactory(lockFactory);    // 设置当前FSDirectory相关锁工厂实例

    if (doClearLockID) {
      // Clear the prefix because write.lock will be
      // stored in our directory:
      lockFactory.setLockPrefix(null);
    }
}

// 返回目录文件File directory下的所有索引文件，索引文件使用文件名的字符串描述
public String[] list() {
    return directory.list(IndexFileNameFilter.getFilter());
}

// 如果文件name存在，则返回true
public boolean fileExists(String name) {
    File file = new File(directory, name);    // 根据File directory指定的抽象路径，以及name指定的名称创建一个文件
    return file.exists();
}

// 获取文件name最后修改的时间
public long fileModified(String name) {
    File file = new File(directory, name);
    return file.lastModified();
}

// 返回目录文件directory下名称为name的文件最后修改的时间
public static long fileModified(File directory, String name) {
    File file = new File(directory, name);
    return file.lastModified();
}

// 设置文件name当前修改的时间
public void touchFile(String name) {
    File file = new File(directory, name);
    file.setLastModified(System.currentTimeMillis());
}

// 获取文件name的长度
public long fileLength(String name) {
    File file = new File(directory, name);
    return file.length();
}

// 删除目录文件directory下的name文件
public void deleteFile(String name) throws IOException {
    File file = new File(directory, name);
    if (!file.delete())
      throw new IOException("Cannot delete " + file);
}

// 重新命名文件，该方法已经废弃
public synchronized void renameFile(String from, String to)
      throws IOException {
    File old = new File(directory, from);
    File nu = new File(directory, to);

    if (nu.exists())
      if (!nu.delete())
        throw new IOException("Cannot delete " + nu);
    if (!old.renameTo(nu)) {
      java.io.InputStream in = null;
      java.io.OutputStream out = null;
      try {
        in = new FileInputStream(old);
        out = new FileOutputStream(nu);
        if (buffer == null) {
          buffer = new byte[1024];
        }
        int len;
        while ((len = in.read(buffer)) >= 0) {
          out.write(buffer, 0, len);
        }

        old.delete();
      }
      catch (IOException ioe) {
        IOException newExc = new IOException("Cannot rename " + old + " to " + nu);
        newExc.initCause(ioe);
        throw newExc;
      }
      finally {
        try {
          if (in != null) {
            try {
              in.close();
            } catch (IOException e) {
              throw new RuntimeException("Cannot close input stream: " + e.toString(), e);
            }
          }
        } finally {
          if (out != null) {
            try {
              out.close();
            } catch (IOException e) {
              throw new RuntimeException("Cannot close output stream: " + e.toString(), e);
            }
          }
        }
      }
    }
}

// 创建一个名称为name的文件，返回一个输出流，以便对该文件进行写入操作
public IndexOutput createOutput(String name) throws IOException {

    File file = new File(directory, name);
    if (file.exists() && !file.delete())          // 如果name指定文件存在，或者没有被删除掉，抛出异常
      throw new IOException("Cannot overwrite: " + file);

    return new FSIndexOutput(file);    // 返回文件File file的一个输出流
}

  // 读取名称为name的文件，返回一个输出流，以便定义对读取出来的内容进行操作
public IndexInput openInput(String name) throws IOException {
    return new FSIndexInput(new File(directory, name));
}

// 打开指定名称为name的文件，指定大小为缓冲区大小bufferSize，返回一个输入流
public IndexInput openInput(String name, int bufferSize) throws IOException {
    return new FSIndexInput(new File(directory, name), bufferSize);
}

// 一个字符缓冲区，将字节转换为十六进制
private static final char[] HEX_DIGITS =
{'0','1','2','3','4','5','6','7','8','9','a','b','c','d','e','f'};

// 获取锁的标识ID
public String getLockID() {
    String dirName;                               
    try {
      dirName = directory.getCanonicalPath();
    } catch (IOException e) {
      throw new RuntimeException(e.toString(), e);
    }

    byte digest[];
    synchronized (DIGESTER) {
      digest = DIGESTER.digest(dirName.getBytes());
    }
    StringBuffer buf = new StringBuffer();
    buf.append("lucene-");
    for (int i = 0; i < digest.length; i++) {
      int b = digest[i];
      buf.append(HEX_DIGITS[(b >> 4) & 0xf]);
      buf.append(HEX_DIGITS[b & 0xf]);
    }

    return buf.toString();
}

// 关闭目录
public synchronized void close() {
    if (--refCount <= 0) {
      synchronized (DIRECTORIES) {
        DIRECTORIES.remove(directory);
      }
    }
}

public File getFile() {
    return directory;
}

/** For debug output. */
public String toString() {
    return this.getClass().getName() + "@" + directory;
}

// FSIndexInput是一个静态内部类，用于管理文件系统中的索引文件输入流

protected static class FSIndexInput extends BufferedIndexInput {

    private static class Descriptor extends RandomAccessFile {
      // 用于记录文件打开状态的boolean型变量isOpen
      private boolean isOpen;
      long position;
      final long length;
     
      public Descriptor(File file, String mode) throws IOException {
        super(file, mode);
        isOpen=true;
        length=length();
      }

      public void close() throws IOException {
        if (isOpen) {
          isOpen=false;
          super.close();
        }
      }

      protected void finalize() throws Throwable {
        try {
          close();
        } finally {
          super.finalize();
        }
      }
    }

    private final Descriptor file;
    boolean isClone;

    public FSIndexInput(File path) throws IOException {
      this(path, BufferedIndexInput.BUFFER_SIZE);
    }

    public FSIndexInput(File path, int bufferSize) throws IOException {
      super(bufferSize);
      file = new Descriptor(path, "r");
    }

    // 比较底层的读取操作，主要是对字节操作
    protected void readInternal(byte[] b, int offset, int len)
         throws IOException {
      synchronized (file) {
        long position = getFilePointer();
        if (position != file.position) {
          file.seek(position);
          file.position = position;
        }
        int total = 0;
        do {
          int i = file.read(b, offset+total, len-total);
          if (i == -1)
            throw new IOException("read past EOF");
          file.position += i;
          total += i;
        } while (total < len);
      }
    }

    public void close() throws IOException {
      if (!isClone) file.close();
    }

    protected void seekInternal(long position) {
    }

    public long length() {
      return file.length;
    }

    public Object clone() {
      FSIndexInput clone = (FSIndexInput)super.clone();
      clone.isClone = true;
      return clone;
    }

    /** Method used for testing. Returns true if the underlying
     * file descriptor is valid.
     */
    boolean isFDValid() throws IOException {
      return file.getFD().valid();
    }
}

// FSIndexOutput是一个静态内部类，用于管理文件系统中的索引文件输出流，与FSIndexInput实现类似

protected static class FSIndexOutput extends BufferedIndexOutput {
    RandomAccessFile file = null;
  
    // 用于记录文件打开状态的boolean型变量isOpen   
    private boolean isOpen;

    public FSIndexOutput(File path) throws IOException {
      file = new RandomAccessFile(path, "rw");
      isOpen = true;
    }
  
   // 从缓冲区写入文件的方法
    public void flushBuffer(byte[] b, int offset, int size) throws IOException {
      file.write(b, offset, size);
    }
    public void close() throws IOException {
      if (isOpen) {
        super.close();
        file.close();
        isOpen = false;
      }
    }

    // 随机访问的方法实现
    public void seek(long pos) throws IOException {
      super.seek(pos);
      file.seek(pos);
    }
    public long length() throws IOException {
      return file.length();
    }

}
}

上面FSDirectory类的实现挺复杂的，主要是在继承Directory抽象类的基础上，增加了文件系统目录锁特有的一些操作方式。

通过FSDirectory类源代码的阅读，关于文件系统目录FSDirectory类，总结几点：

1、锁工厂的获取及其管理；

2、对文件系统目录下索引文件的输入流和输出流的管理；

3、获取FSDirectory类实例；

4、获取锁工厂实例后，可以创建一个新的FSDirectory类实例，在此之前先要完成一些初始化工作；

5、继承自Directory抽象类，自然可以实现索引文件的的拷贝操作。

6、FSDirectory类中实现了很多静态内部类，这使得只能在FSDirectory类内部访问这些静态类，对外部透明。