FileDocCategorySizeDatePackage
FSDirectory.javaAPI DocApache Lucene 2.2.020366Sat Jun 16 22:20:36 BST 2007org.apache.lucene.store

FSDirectory

public class FSDirectory extends Directory
Straightforward implementation of {@link Directory} as a directory of files. Locking implementation is by default the {@link SimpleFSLockFactory}, but can be changed either by passing in a {@link LockFactory} instance to getDirectory, or specifying the LockFactory class by setting org.apache.lucene.store.FSDirectoryLockFactoryClass Java system property, or by calling {@link #setLockFactory} after creating the Directory.

Directories are cached, so that, for a given canonical path, the same FSDirectory instance will always be returned by getDirectory. This permits synchronization on directories.

see
Directory
author
Doug Cutting

Fields Summary
private static final Hashtable
DIRECTORIES
This cache of directories ensures that there is a unique Directory instance per path, so that synchronization on the Directory can be used to synchronize access between readers and writers. We use refcounts to ensure when the last use of an FSDirectory instance for a given canonical path is closed, we remove the instance from the cache. See LUCENE-776 for some relevant discussion.
private static boolean
disableLocks
public static final String
LOCK_DIR
Directory specified by org.apache.lucene.lockDir or java.io.tmpdir system property.
private static Class
IMPL
The default class which implements filesystem-based directories.
private static MessageDigest
DIGESTER
private byte[]
buffer
A buffer optionally used in renameTo method
private File
directory
private int
refCount
private static final char[]
HEX_DIGITS
So we can do some byte-to-hexchar conversion below
Constructors Summary
protected FSDirectory()


    
Methods Summary
public synchronized voidclose()
Closes the store to future operations.

    if (--refCount <= 0) {
      synchronized (DIRECTORIES) {
        DIRECTORIES.remove(directory);
      }
    }
  
private voidcreate()

    if (directory.exists()) {
      String[] files = directory.list(IndexFileNameFilter.getFilter());            // clear old files
      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);
  
public org.apache.lucene.store.IndexOutputcreateOutput(java.lang.String name)
Creates a new, empty file in the directory with the given name. Returns a stream writing this file.


    File file = new File(directory, name);
    if (file.exists() && !file.delete())          // delete existing, if any
      throw new IOException("Cannot overwrite: " + file);

    return new FSIndexOutput(file);
  
public voiddeleteFile(java.lang.String name)
Removes an existing file in the directory.

    File file = new File(directory, name);
    if (!file.delete())
      throw new IOException("Cannot delete " + file);
  
public booleanfileExists(java.lang.String name)
Returns true iff a file with the given name exists.

    File file = new File(directory, name);
    return file.exists();
  
public longfileLength(java.lang.String name)
Returns the length in bytes of a file in the directory.

    File file = new File(directory, name);
    return file.length();
  
public longfileModified(java.lang.String name)
Returns the time the named file was last modified.

    File file = new File(directory, name);
    return file.lastModified();
  
public static longfileModified(java.io.File directory, java.lang.String name)
Returns the time the named file was last modified.

    File file = new File(directory, name);
    return file.lastModified();
  
public static org.apache.lucene.store.FSDirectorygetDirectory(java.lang.String path)
Returns the directory instance for the named location.

param
path the path to the directory.
return
the FSDirectory for the named file.


                          
      
        
    return getDirectory(new File(path), null);
  
public static org.apache.lucene.store.FSDirectorygetDirectory(java.lang.String path, org.apache.lucene.store.LockFactory lockFactory)
Returns the directory instance for the named location.

param
path the path to the directory.
param
lockFactory instance of {@link LockFactory} providing the locking implementation.
return
the FSDirectory for the named file.

    return getDirectory(new File(path), lockFactory);
  
public static org.apache.lucene.store.FSDirectorygetDirectory(java.io.File file)
Returns the directory instance for the named location.

param
file the path to the directory.
return
the FSDirectory for the named file.

    return getDirectory(file, null);
  
public static org.apache.lucene.store.FSDirectorygetDirectory(java.io.File file, org.apache.lucene.store.LockFactory lockFactory)
Returns the directory instance for the named location.

param
file the path to the directory.
param
lockFactory instance of {@link LockFactory} providing the locking implementation.
return
the FSDirectory for the named file.

    file = new File(file.getCanonicalPath());

    if (file.exists() && !file.isDirectory())
      throw new IOException(file + " not a directory");

    if (!file.exists())
      if (!file.mkdirs())
        throw new IOException("Cannot create directory: " + file);

    FSDirectory dir;
    synchronized (DIRECTORIES) {
      dir = (FSDirectory)DIRECTORIES.get(file);
      if (dir == null) {
        try {
          dir = (FSDirectory)IMPL.newInstance();
        } catch (Exception e) {
          throw new RuntimeException("cannot load FSDirectory class: " + e.toString(), e);
        }
        dir.init(file, lockFactory);
        DIRECTORIES.put(file, dir);
      } else {
        // Catch the case where a Directory is pulled from the cache, but has a
        // different LockFactory instance.
        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++;
    }
    return dir;
  
public static org.apache.lucene.store.FSDirectorygetDirectory(java.lang.String path, boolean create)
Returns the directory instance for the named location.

deprecated
Use IndexWriter's create flag, instead, to create a new index.
param
path the path to the directory.
param
create if true, create, or erase any existing contents.
return
the FSDirectory for the named file.

    return getDirectory(new File(path), create);
  
public static org.apache.lucene.store.FSDirectorygetDirectory(java.io.File file, boolean create)
Returns the directory instance for the named location.

deprecated
Use IndexWriter's create flag, instead, to create a new index.
param
file the path to the directory.
param
create if true, create, or erase any existing contents.
return
the FSDirectory for the named file.

    FSDirectory dir = getDirectory(file, null);

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

    return dir;
  
public static booleangetDisableLocks()
Returns whether Lucene's use of lock files is disabled.

return
true if locks are disabled, false if locks are enabled.

    return FSDirectory.disableLocks;
  
public java.io.FilegetFile()

    return directory;
  
public java.lang.StringgetLockID()


  
     
    String dirName;                               // name to be hashed
    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();
  
private voidinit(java.io.File path, org.apache.lucene.store.LockFactory lockFactory)


    // Set up lockFactory with cascaded defaults: if an instance was passed in,
    // use that; else if locks are disabled, use NoLockFactory; else if the
    // system property org.apache.lucene.store.FSDirectoryLockFactoryClass is set,
    // instantiate that; else, use SimpleFSLockFactory:

    directory = path;

    boolean doClearLockID = false;

    if (lockFactory == null) {

      if (disableLocks) {
        // Locks are disabled:
        lockFactory = NoLockFactory.getNoLockFactory();
      } else {
        String lockClassName = System.getProperty("org.apache.lucene.store.FSDirectoryLockFactoryClass");

        if (lockClassName != null && !lockClassName.equals("")) {
          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");
          }

          if (lockFactory instanceof NativeFSLockFactory) {
            ((NativeFSLockFactory) lockFactory).setLockDir(path);
          } else if (lockFactory instanceof SimpleFSLockFactory) {
            ((SimpleFSLockFactory) lockFactory).setLockDir(path);
          }
        } else {
          // Our default lock is SimpleFSLockFactory;
          // default lockDir is our index directory:
          lockFactory = new SimpleFSLockFactory(path);
          doClearLockID = true;
        }
      }
    }

    setLockFactory(lockFactory);

    if (doClearLockID) {
      // Clear the prefix because write.lock will be
      // stored in our directory:
      lockFactory.setLockPrefix(null);
    }
  
public java.lang.String[]list()
Returns an array of strings, one for each Lucene index file in the directory.

    return directory.list(IndexFileNameFilter.getFilter());
  
public org.apache.lucene.store.IndexInputopenInput(java.lang.String name)

    return new FSIndexInput(new File(directory, name));
  
public org.apache.lucene.store.IndexInputopenInput(java.lang.String name, int bufferSize)

    return new FSIndexInput(new File(directory, name), bufferSize);
  
public synchronized voidrenameFile(java.lang.String from, java.lang.String to)
Renames an existing file in the directory. Warning: This is not atomic.

deprecated

    File old = new File(directory, from);
    File nu = new File(directory, to);

    /* This is not atomic.  If the program crashes between the call to
       delete() and the call to renameTo() then we're screwed, but I've
       been unable to figure out how else to do this... */

    if (nu.exists())
      if (!nu.delete())
        throw new IOException("Cannot delete " + nu);

    // Rename the old file to the new one. Unfortunately, the renameTo()
    // method does not work reliably under some JVMs.  Therefore, if the
    // rename fails, we manually rename by copying the old file to the new one
    if (!old.renameTo(nu)) {
      java.io.InputStream in = null;
      java.io.OutputStream out = null;
      try {
        in = new FileInputStream(old);
        out = new FileOutputStream(nu);
        // see if the buffer needs to be initialized. Initialization is
        // only done on-demand since many VM's will never run into the renameTo
        // bug and hence shouldn't waste 1K of mem for no reason.
        if (buffer == null) {
          buffer = new byte[1024];
        }
        int len;
        while ((len = in.read(buffer)) >= 0) {
          out.write(buffer, 0, len);
        }

        // delete the old file.
        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);
            }
          }
        }
      }
    }
  
public static voidsetDisableLocks(boolean doDisableLocks)
Set whether Lucene's use of lock files is disabled. By default, lock files are enabled. They should only be disabled if the index is on a read-only medium like a CD-ROM.


  // TODO: should this move up to the Directory base class?  Also: should we
  // make a per-instance (in addition to the static "default") version?

                                     
       
    FSDirectory.disableLocks = doDisableLocks;
  
public java.lang.StringtoString()
For debug output.

    return this.getClass().getName() + "@" + directory;
  
public voidtouchFile(java.lang.String name)
Set the modified time of an existing file to now.

    File file = new File(directory, name);
    file.setLastModified(System.currentTimeMillis());