org.apache.lucene.store
Class Directory

java.lang.Object
  extended by org.apache.lucene.store.Directory
All Implemented Interfaces:
Closeable
Direct Known Subclasses:
FileSwitchDirectory, FSDirectory, NRTCachingDirectory, RAMDirectory

public abstract class Directory
extends Object
implements Closeable

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.

Java's i/o APIs not used directly, but rather all i/o is through this API. This permits things such as:

Directory locking is implemented by an instance of LockFactory, and can be changed for each Directory instance using setLockFactory(org.apache.lucene.store.LockFactory).


Field Summary
protected  boolean isOpen
           
protected  LockFactory lockFactory
          Holds the LockFactory instance (implements locking for this Directory instance).
 
Constructor Summary
Directory()
           
 
Method Summary
 void clearLock(String name)
          Attempt to clear (forcefully unlock and remove) the specified lock.
abstract  void close()
          Closes the store.
static void copy(Directory src, Directory dest, boolean closeDirSrc)
          Deprecated. should be replaced with calls to copy(Directory, String, String) for every file that needs copying. You can use the following code:
 IndexFileNameFilter filter = IndexFileNameFilter.getFilter();
 for (String file : src.listAll()) {
   if (filter.accept(null, file)) {
     src.copy(dest, file, file);
   }
 }
 
 void copy(Directory to, String src, String dest)
          Copies the file src to Directory to under the new file name dest.
abstract  IndexOutput createOutput(String name)
          Creates a new, empty file in the directory with the given name.
abstract  void deleteFile(String name)
          Removes an existing file in the directory.
protected  void ensureOpen()
           
abstract  boolean fileExists(String name)
          Returns true iff a file with the given name exists.
abstract  long fileLength(String name)
          Returns the length of a file in the directory.
abstract  long fileModified(String name)
          Returns the time the named file was last modified.
 LockFactory getLockFactory()
          Get the LockFactory that this Directory instance is using for its locking implementation.
 String getLockID()
          Return a string identifier that uniquely differentiates this Directory instance from other Directory instances.
abstract  String[] listAll()
          Returns an array of strings, one for each file in the directory.
 Lock makeLock(String name)
          Construct a Lock.
abstract  IndexInput openInput(String name)
          Returns a stream reading an existing file.
 IndexInput openInput(String name, int bufferSize)
          Returns a stream reading an existing file, with the specified read buffer size.
 void setLockFactory(LockFactory lockFactory)
          Set the LockFactory that this Directory instance should use for its locking implementation.
 void sync(Collection<String> names)
          Ensure that any writes to these files are moved to stable storage.
 void sync(String name)
          Deprecated. use sync(Collection) instead. For easy migration you can change your code to call sync(Collections.singleton(name))
 String toString()
           
abstract  void touchFile(String name)
          Deprecated. Lucene never uses this API; it will be removed in 4.0.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

isOpen

protected volatile boolean isOpen

lockFactory

protected LockFactory lockFactory
Holds the LockFactory instance (implements locking for this Directory instance).

Constructor Detail

Directory

public Directory()
Method Detail

listAll

public abstract String[] listAll()
                          throws IOException
Returns an array of strings, one for each file in the directory.

Throws:
NoSuchDirectoryException - if the directory is not prepared for any write operations (such as createOutput(String)).
IOException - in case of other IO errors

fileExists

public abstract boolean fileExists(String name)
                            throws IOException
Returns true iff a file with the given name exists.

Throws:
IOException

fileModified

public abstract long fileModified(String name)
                           throws IOException
Returns the time the named file was last modified.

Throws:
IOException

touchFile

@Deprecated
public abstract void touchFile(String name)
                        throws IOException
Deprecated. Lucene never uses this API; it will be removed in 4.0.

Set the modified time of an existing file to now.

Throws:
IOException

deleteFile

public abstract void deleteFile(String name)
                         throws IOException
Removes an existing file in the directory.

Throws:
IOException

fileLength

public abstract long fileLength(String name)
                         throws IOException
Returns the length of a file in the directory. This method follows the following contract:

Parameters:
name - the name of the file for which to return the length.
Throws:
FileNotFoundException - if the file does not exist.
IOException - if there was an IO error while retrieving the file's length.

createOutput

public abstract IndexOutput createOutput(String name)
                                  throws IOException
Creates a new, empty file in the directory with the given name. Returns a stream writing this file.

Throws:
IOException

sync

@Deprecated
public void sync(String name)
          throws IOException
Deprecated. use sync(Collection) instead. For easy migration you can change your code to call sync(Collections.singleton(name))

Ensure that any writes to this file are moved to stable storage. Lucene uses this to properly commit changes to the index, to prevent a machine/OS crash from corrupting the index.

Throws:
IOException

sync

public void sync(Collection<String> names)
          throws IOException
Ensure that any writes to these files are moved to stable storage. Lucene uses this to properly commit changes to the index, to prevent a machine/OS crash from corrupting the index.

NOTE: Clients may call this method for same files over and over again, so some impls might optimize for that. For other impls the operation can be a noop, for various reasons.

Throws:
IOException

openInput

public abstract IndexInput openInput(String name)
                              throws IOException
Returns a stream reading an existing file.

Throws:
IOException

openInput

public IndexInput openInput(String name,
                            int bufferSize)
                     throws IOException
Returns a stream reading an existing file, with the specified read buffer size. The particular Directory implementation may ignore the buffer size. Currently the only Directory implementations that respect this parameter are FSDirectory and CompoundFileReader.

Throws:
IOException

makeLock

public Lock makeLock(String name)
Construct a Lock.

Parameters:
name - the name of the lock file

clearLock

public void clearLock(String name)
               throws IOException
Attempt to clear (forcefully unlock and remove) the specified lock. Only call this at a time when you are certain this lock is no longer in use.

Parameters:
name - name of the lock to be cleared.
Throws:
IOException

close

public abstract void close()
                    throws IOException
Closes the store.

Specified by:
close in interface Closeable
Throws:
IOException

setLockFactory

public void setLockFactory(LockFactory lockFactory)
                    throws IOException
Set the LockFactory that this Directory instance should use for its locking implementation. Each * instance of LockFactory should only be used for one directory (ie, do not share a single instance across multiple Directories).

Parameters:
lockFactory - instance of LockFactory.
Throws:
IOException

getLockFactory

public LockFactory getLockFactory()
Get the LockFactory that this Directory instance is using for its locking implementation. Note that this may be null for Directory implementations that provide their own locking implementation.


getLockID

public String getLockID()
Return a string identifier that uniquely differentiates this Directory instance from other Directory instances. This ID should be the same if two Directory instances (even in different JVMs and/or on different machines) are considered "the same index". This is how locking "scopes" to the right index.


toString

public String toString()
Overrides:
toString in class Object

copy

public void copy(Directory to,
                 String src,
                 String dest)
          throws IOException
Copies the file src to Directory to under the new file name dest.

If you want to copy the entire source directory to the destination one, you can do so like this:

 Directory to; // the directory to copy to
 for (String file : dir.listAll()) {
   dir.copy(to, file, newFile); // newFile can be either file, or a new name
 }
 

NOTE: this method does not check whether dest exist and will overwrite it if it does.

Throws:
IOException

copy

@Deprecated
public static void copy(Directory src,
                                   Directory dest,
                                   boolean closeDirSrc)
                 throws IOException
Deprecated. should be replaced with calls to copy(Directory, String, String) for every file that needs copying. You can use the following code:
 IndexFileNameFilter filter = IndexFileNameFilter.getFilter();
 for (String file : src.listAll()) {
   if (filter.accept(null, file)) {
     src.copy(dest, file, file);
   }
 }
 

Copy contents of a directory src to a directory dest. If a file in src already exists in dest then the one in dest will be blindly overwritten.

NOTE: the source directory cannot change while this method is running. Otherwise the results are undefined and you could easily hit a FileNotFoundException.

NOTE: this method only copies files that look like index files (ie, have extensions matching the known extensions of index files).

Parameters:
src - source directory
dest - destination directory
closeDirSrc - if true, call close() method on source directory
Throws:
IOException

ensureOpen

protected final void ensureOpen()
                         throws AlreadyClosedException
Throws:
AlreadyClosedException - if this Directory is closed


Copyright © 2000-2011 Apache Software Foundation. All Rights Reserved.