svn commit: r1702622 - in /lucene/dev/branches/branch_5x: ./ lucene/ lucene/CHANGES.txt lucene/core/ lucene/core/src/java/org/apache/lucene/store/FSDirectory.java

[us...@apache.org]

Author: uschindler
Date: Sat Sep 12 11:46:26 2015
New Revision: 1702622

URL: http://svn.apache.org/r1702622
Log:
Merged revision(s) 1702619-1702621 from lucene/dev/trunk:
LUCENE-6770: Add javadocs that FSDirectory canonicalizes the path

Modified:
    lucene/dev/branches/branch_5x/   (props changed)
    lucene/dev/branches/branch_5x/lucene/   (props changed)
    lucene/dev/branches/branch_5x/lucene/CHANGES.txt   (contents, props changed)
    lucene/dev/branches/branch_5x/lucene/core/   (props changed)
    lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java

Modified: lucene/dev/branches/branch_5x/lucene/CHANGES.txt
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_5x/lucene/CHANGES.txt?rev=1702622&r1=1702621&r2=1702622&view=diff
==============================================================================
--- lucene/dev/branches/branch_5x/lucene/CHANGES.txt (original)
+++ lucene/dev/branches/branch_5x/lucene/CHANGES.txt Sat Sep 12 11:46:26 2015
@@ -114,6 +114,9 @@ Other
 * LUCENE-6798: Geo3d now models degenerate (too tiny) circles as a
   single point (Karl Wright via Mike McCandless)
 
+* LUCENE-6770: Add javadocs that FSDirectory canonicalizes the path.
+  (Uwe Schindler, Vladimir Kuzmin)
+
 Build
 
 * LUCENE-6732: Improve checker for invalid source patterns to also

Modified: lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java?rev=1702622&r1=1702621&r2=1702622&view=diff
==============================================================================
--- lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java (original)
+++ lucene/dev/branches/branch_5x/lucene/core/src/java/org/apache/lucene/store/FSDirectory.java Sat Sep 12 11:46:26 2015
@@ -117,6 +117,12 @@ public abstract class FSDirectory extend
 
   /** Create a new FSDirectory for the named location (ctor for subclasses).
    * The directory is created at the named location if it does not yet exist.
+   * 
+   * <p>{@code FSDirectory} resolves the given Path to a canonical /
+   * real path to ensure it can correctly lock the index directory and no other process
+   * can interfere with changing possible symlinks to the index directory inbetween.
+   * If you want to use symlinks and change them dynamically, close all
+   * {@code IndexWriters} and create a new {@code FSDirecory} instance.
    * @param path the path of the directory
    * @param lockFactory the lock factory to use, or null for the default
    * ({@link NativeFSLockFactory});
@@ -135,6 +141,12 @@ public abstract class FSDirectory extend
    *  best implementation given the current environment.
    *  The directory returned uses the {@link NativeFSLockFactory}.
    *  The directory is created at the named location if it does not yet exist.
+   * 
+   * <p>{@code FSDirectory} resolves the given Path when calling this method to a canonical /
+   * real path to ensure it can correctly lock the index directory and no other process
+   * can interfere with changing possible symlinks to the index directory inbetween.
+   * If you want to use symlinks and change them dynamically, close all
+   * {@code IndexWriters} and create a new {@code FSDirecory} instance.
    *
    *  <p>Currently this returns {@link MMapDirectory} for Linux, MacOSX, Solaris,
    *  and Windows 64-bit JREs, {@link NIOFSDirectory} for other