--- /dev/null
+package org.apache.lucene.store;
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import java.io.FileNotFoundException;
+import java.io.IOException;
+import java.io.Closeable;
+import java.util.Collection;
+
+import org.apache.lucene.index.IndexFileNameFilter;
+import org.apache.lucene.util.IOUtils;
+
+/** 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>
+ *
+ * Directory locking is implemented by an instance of {@link
+ * LockFactory}, and can be changed for each Directory
+ * instance using {@link #setLockFactory}.
+ *
+ */
+public abstract class Directory implements Closeable {
+
+ volatile protected boolean isOpen = true;
+
+ /** Holds the LockFactory instance (implements locking for
+ * this Directory instance). */
+ protected LockFactory lockFactory;
+
+ /**
+ * 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 {@link #createOutput(String)}).
+ * @throws IOException in case of other IO errors
+ */
+ public abstract String[] listAll() throws IOException;
+
+ /** Returns true iff a file with the given name exists. */
+ public abstract boolean fileExists(String name)
+ throws IOException;
+
+ /** Returns the time the named file was last modified. */
+ public abstract long fileModified(String name)
+ throws IOException;
+
+ /** Set the modified time of an existing file to now.
+ *
+ * @deprecated Lucene never uses this API; it will be
+ * removed in 4.0. */
+ @Deprecated
+ public abstract void touchFile(String name)
+ throws IOException;
+
+ /** Removes an existing file in the directory. */
+ public abstract void deleteFile(String name)
+ throws IOException;
+
+ /**
+ * Returns the length of a file in the directory. This method follows the
+ * following contract:
+ * <ul>
+ * <li>Throws {@link FileNotFoundException} if the file does not exist
+ * <li>Returns a value ≥0 if the file exists, which specifies its length.
+ * </ul>
+ *
+ * @param name the name of the file for which to return the length.
+ * @throws FileNotFoundException if the file does not exist.
+ * @throws IOException if there was an IO error while retrieving the file's
+ * length.
+ */
+ public abstract long fileLength(String name) throws IOException;
+
+
+ /** Creates a new, empty file in the directory with the given name.
+ Returns a stream writing this file. */
+ public abstract IndexOutput createOutput(String name)
+ throws IOException;
+
+ /**
+ * 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.
+ * @deprecated use {@link #sync(Collection)} instead.
+ * For easy migration you can change your code to call
+ * sync(Collections.singleton(name))
+ */
+ @Deprecated
+ public void sync(String name) throws IOException { // TODO 4.0 kill me
+ }
+
+ /**
+ * 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.<br/>
+ * <br/>
+ * 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.
+ */
+ public void sync(Collection<String> names) throws IOException { // TODO 4.0 make me abstract
+ for (String name : names)
+ sync(name);
+ }
+
+ /** Returns a stream reading an existing file. */
+ public abstract IndexInput openInput(String name)
+ 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 {@link FSDirectory} and {@link
+ * org.apache.lucene.index.CompoundFileReader}.
+ */
+ public IndexInput openInput(String name, int bufferSize) throws IOException {
+ return openInput(name);
+ }
+
+ /** Construct a {@link Lock}.
+ * @param name the name of the lock file
+ */
+ public Lock makeLock(String name) {
+ return lockFactory.makeLock(name);
+ }
+ /**
+ * 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.
+ * @param name name of the lock to be cleared.
+ */
+ public void clearLock(String name) throws IOException {
+ if (lockFactory != null) {
+ lockFactory.clearLock(name);
+ }
+ }
+
+ /** Closes the store. */
+ public abstract void close()
+ 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).
+ *
+ * @param lockFactory instance of {@link LockFactory}.
+ */
+ public void setLockFactory(LockFactory lockFactory) throws IOException {
+ assert lockFactory != null;
+ this.lockFactory = lockFactory;
+ lockFactory.setLockPrefix(this.getLockID());
+ }
+
+ /**
+ * 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.
+ */
+ public LockFactory getLockFactory() {
+ return this.lockFactory;
+ }
+
+ /**
+ * 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.
+ */
+ public String getLockID() {
+ return this.toString();
+ }
+
+ @Override
+ public String toString() {
+ return super.toString() + " lockFactory=" + getLockFactory();
+ }
+
+ /**
+ * Copies the file <i>src</i> to {@link Directory} <i>to</i> under the new
+ * file name <i>dest</i>.
+ * <p>
+ * If you want to copy the entire source directory to the destination one, you
+ * can do so like this:
+ *
+ * <pre>
+ * 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
+ * }
+ * </pre>
+ * <p>
+ * <b>NOTE:</b> this method does not check whether <i>dest<i> exist and will
+ * overwrite it if it does.
+ */
+ public void copy(Directory to, String src, String dest) throws IOException {
+ IndexOutput os = null;
+ IndexInput is = null;
+ IOException priorException = null;
+ try {
+ os = to.createOutput(dest);
+ is = openInput(src);
+ is.copyBytes(os, is.length());
+ } catch (IOException ioe) {
+ priorException = ioe;
+ } finally {
+ IOUtils.closeWhileHandlingException(priorException, os, is);
+ }
+ }
+
+ /**
+ * 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.
+ * <p>
+ * <b>NOTE:</b> the source directory cannot change while this method is
+ * running. Otherwise the results are undefined and you could easily hit a
+ * FileNotFoundException.
+ * <p>
+ * <b>NOTE:</b> this method only copies files that look like index files (ie,
+ * have extensions matching the known extensions of index files).
+ *
+ * @param src source directory
+ * @param dest destination directory
+ * @param closeDirSrc if <code>true</code>, call {@link #close()} method on
+ * source directory
+ * @deprecated should be replaced with calls to
+ * {@link #copy(Directory, String, String)} for every file that
+ * needs copying. You can use the following code:
+ *
+ * <pre>
+ * IndexFileNameFilter filter = IndexFileNameFilter.getFilter();
+ * for (String file : src.listAll()) {
+ * if (filter.accept(null, file)) {
+ * src.copy(dest, file, file);
+ * }
+ * }
+ * </pre>
+ */
+ @Deprecated
+ public static void copy(Directory src, Directory dest, boolean closeDirSrc) throws IOException {
+ IndexFileNameFilter filter = IndexFileNameFilter.getFilter();
+ for (String file : src.listAll()) {
+ if (filter.accept(null, file)) {
+ src.copy(dest, file, file);
+ }
+ }
+ if (closeDirSrc) {
+ src.close();
+ }
+ }
+
+ /**
+ * @throws AlreadyClosedException if this Directory is closed
+ */
+ protected final void ensureOpen() throws AlreadyClosedException {
+ if (!isOpen)
+ throw new AlreadyClosedException("this Directory is closed");
+ }
+}
fnp / pylucene.git / blobdiff